@cryptotaxi247 / netdata / commits / b695fa41f

chore: clarify the SOW lifecycle and strengthen the Mandatory Development Principles (#22630)

Ilya Mashchenko committed Jun 4, 2026 at 14:29 UTC b695fa41f8ef49b983cde3842fcf8db9d7bca780
4 files changed +387 -37
.agents/sow/SOW.template.md
+13 -6
@@ -5,9 +5,9 @@
5 Status: planning | ready | in-progress | paused | completed
6
7 `planning` means analysis or decisions are incomplete. `ready` means the
8 -Pre-Implementation Gate is complete and implementation can start. `completed`
9 -is a transient branch-local state before deleting this SOW working file before
10 -merge. SOW files live only under `.agents/sow/active/` on feature branches and
8 +Pre-Implementation Gate is complete and, where the goal-approval round ("Plan
9 +before non-trivial work") applies, the user has approved the goal and plan. `completed` is a
10 +transient branch-local state before deleting this SOW working file before merge. SOW files live only under `.agents/sow/active/` on feature branches and
11 MUST NOT be merged to `master`.
12
13 Sub-state: <short current truth>
@@ -68,12 +68,19 @@ Problem / root-cause model:
68 Evidence reviewed:
69
70 - <Specs, code, docs, tests, logs, traces, prior PRs/issues, external references.>
71 -- <For mirrored open-source repositories: cite `owner/repo @ commit` and repository-relative paths; never paste `/opt/baddisk/monitoring/repos/...` absolute paths.>
71 +- <For mirrored open-source repositories: cite `owner/repo @ commit` and repository-relative paths; never paste machine-specific absolute mirror paths (the mirror lives at `${NETDATA_REPOS_DIR}`).>
72
73 Affected contracts and surfaces:
74
75 - <APIs, schemas, files, commands, UI, docs, specs, skills, tests, integrations, operators, users.>
76
77 +Clean-end-state target:
78 +
79 +- <The structure the codebase should have once the approved scope is fully delivered.>
80 +- Removed as redundant (i): <code/config/docs/tests this change makes redundant.>
81 +- Excluded coupled items (ii): <coupled items NOT part of this clean end state, each with reason + scope source.>
82 +- Reference search (when a path/contract is replaced): <command(s) run + result; every surviving reference mapped to (i)/(ii), or the target is incomplete.>
83 +
84 Existing patterns to reuse:
85
86 - <Local modules, helpers, conventions, tests, and docs that shape the implementation.>
@@ -106,7 +113,7 @@ Artifact impact plan:
113
114 Open-source reference evidence:
115
109 -- <If local mirrored repositories under `/opt/baddisk/monitoring/repos/` were checked, list each as `owner/repo @ commit` plus repository-relative paths. If none were checked, record why external OSS references were not relevant.>
116 +- <If local mirrored repositories under `${NETDATA_REPOS_DIR}` were checked, list each as `owner/repo @ commit` plus repository-relative paths. If none were checked, record why external OSS references were not relevant.>
117
118 Open decisions:
119
@@ -153,7 +160,7 @@ Sensitive data gate:
160
161 - <Confirm durable artifacts contain no raw secrets, credentials, bearer tokens, SNMP communities, community member names, customer names, personal data, non-private customer-identifying IPs, private endpoints, or proprietary incident details; note redactions used.>
162
156 -Artifact maintenance gate:
163 +## Artifact Maintenance Gate
164
165 - AGENTS.md: <updated path or evidence-backed reason no update was needed>
166 - Runtime project skills: <updated .agents/skills/project-*/ path or evidence-backed reason no update was needed>
.agents/sow/audit.sh
+1
@@ -83,6 +83,7 @@ required_sections=(
83 "### Roles"
84 "### Git Worktrees"
85 "### Sensitive Data In Durable Artifacts"
86 + "### Durable AI-Facing Artifact Formatting"
87 "### Open-Source Reference Evidence"
88 "### Pre-Implementation Gate"
89 "### SOW Completion And Merge"
.github/workflows/sow.yml
+1 -1
@@ -30,7 +30,7 @@ jobs:
30
31 while IFS= read -r file; do
32 [ -n "$file" ] || continue
33 - echo "::error file=${file}::SOW working files are branch-local and must be deleted before merge."
33 + echo "::error file=${file}::SOW working files may be committed for takeover/handoff and must be deleted before merge."
34 found=1
35 done < <(
36 {
AGENTS.md
+372 -30
@@ -30,21 +30,317 @@ CRITICAL RULES:
30
31 ## Mandatory Development Principles
32
33 -These principles are mandatory for every task in this repository:
33 +These principles are mandatory for every task. Code is cheap to add and
34 +expensive to live with, so a larger diff that removes debt beats a smaller one
35 +that preserves it.
36 +
37 +**Core (read first; the bullets under each principle are the authority for forks
38 +and edge cases):**
39 +
40 +- Deliver the **clean end state** of the approved scope, not the smallest diff —
41 + including removing what the change makes redundant; refactor low-risk mess in
42 + code you touch.
43 +- **Record that target in the SOW first** (what you remove; any coupled item you
44 + exclude, with its reason). When you replace a path or contract, record a
45 + reference search proving the list is complete.
46 +- **You are not the scope authority.** Coupled cleanup is in scope: do the
47 + low-risk part and disclose it; never silently drop it or relabel it
48 + "independent."
49 +- Falling short of the recorded target — or any user-owned **fork** (competing
50 + designs, a public-contract or destructive change, unclear scope) — triggers a
51 + **Mandatory pause**: stop, state the trade-off, get explicit approval.
52 +- **Plan before non-trivial work:** establish the user-approved end state plus
53 + acceptance criteria, then ordered steps; re-evaluate against the target at each
54 + step, before any PR, and before completion.
55 +- **Default on doubt:** if unsure whether something is in scope, trivial, or a
56 + user-owned fork, treat it as in-scope / non-trivial / user-owned and ask.
57
58 1. **Clean end state over less churn.**
36 - You MUST always aim for the clean end state, not the smallest diff. While
37 - designing and implementing, actively search for the structure that should
38 - exist after the work is complete. You MUST periodically re-evaluate
39 - already-written changes against that target; do not keep a compromise only
40 - because it already exists in the branch.
41 -
42 -2. **Scope discipline at every step.**
43 - At each milestone, you MUST check whether the work has drifted outside the
44 - approved scope. If the new work is valid but independent, you MUST defer it
45 - to a later step or pause and submit the independent work first, then rebase
46 - the current branch after it merges. Complex features MUST be delivered in
47 - coherent steps where each step builds on the previous one.
59 + - Binding rule (read first): you MUST recommend and deliver the clean end
60 + state — the structure the codebase SHOULD have once the approved scope is
61 + fully delivered, including removing the code, config, docs, and tests the
62 + change makes redundant — not the smallest diff. You MUST NOT relabel the
63 + smallest working diff as "the clean end state."
64 + - Record the target: before generating options, record that clean end state in
65 + the SOW. The recorded target is the clean end state of this SOW's approved
66 + scope; for staged work, each stage's SOW records that stage's target and the
67 + stages together MUST reach the full target. Any option that does not match
68 + the recorded target is a non-clean state and triggers the Mandatory pause.
69 + - Open design decision: when the clean end state is itself an open design
70 + decision that is the user's to make, do not invent a fixed target; record a
71 + provisional target plus the open design question and resolve it with the
72 + user first.
73 + - Approved scope: "the approved scope" is the union of (a) the issue or user
74 + request, (b) the SOW Purpose and Acceptance Criteria, and (c) the
75 + migration/contract surface they imply. If it is unclear whether work is in
76 + scope, treat it as in-scope and raise it with the user; never silently
77 + exclude it.
78 + - You are not the scope authority:
79 + - A "coupled item" is code, config, docs, or tests the current change makes
80 + redundant or leaves inconsistent (for example a replaced path, its
81 + callers, or its tests).
82 + - You MUST NOT reclassify in-scope or coupled work as "independent" or "out
83 + of scope" to avoid doing it, and you MUST NOT silently drop coupled work.
84 + - When you only suspect something is coupled and including it is low-risk and
85 + confined to what you are changing, include it and disclose it rather than
86 + stopping to ask.
87 + - Pause for the user only when including it would expand the blast radius,
88 + change a user-visible contract, or the boundary is itself a genuine scope
89 + fork.
90 + - This overrides any reading of "Scope discipline" that would defer coupled
91 + cleanup.
92 + - Disclose exclusions: in the recorded target you MUST list (i) what you will
93 + remove as redundant, and (ii) any coupled item you are treating as NOT part
94 + of this clean end state, each with its reason and the scope source it rests
95 + on. Excluding an in-scope or coupled item without recording it there is
96 + silent scope-narrowing and is prohibited, so a reviewer or the next agent can
97 + check your exclusions against those sources.
98 + - Touch-the-mess-you-touch: when your change modifies code that already
99 + contains adjacent duplication, dead code, or a clear pre-existing defect, you
100 + SHOULD clean that adjacent mess as part of this work rather than build on top
101 + of it, provided the cleanup is low-risk and confined to the code you are
102 + already modifying. Cleanup that would reach into unrelated code is
103 + independent work (Scope discipline) — track it, do not silently bundle it. If you
104 + choose NOT to clean adjacent mess you touched, record why under the
105 + disclosure list (ii).
106 + - Reference search (when replacing a path or altering a contract):
107 + - You MUST run and record in the SOW a reference search for remaining
108 + references to the replaced path or contract.
109 + - Search construction sites and prefixes too, not only literal final names —
110 + identifiers here are often built dynamically (for example via
111 + `fmt.Sprintf`).
112 + - Every surviving reference MUST appear in (i) or (ii) with its scope source,
113 + or the target is incomplete; an item you did not search for counts as
114 + silent scope-narrowing.
115 + - A repository-wide search cannot prove safety for consumers outside this
116 + repo (Netdata Cloud, exporters, streaming, ML, the docs pipeline); treat
117 + renaming a shipped public contract as a user-owned breaking decision (an
118 + Allowed-exceptions pause), not something the search clears.
119 + - Allowed exceptions (pause conditions, not auto-routes): recommend a
120 + non-clean route ONLY for one of:
121 + - (a) technically impossible — impossible to implement correctly at all, NOT
122 + impossible within a preferred diff size;
123 + - (b) a concrete, evidenced safety risk — a named hazard such as data loss
124 + or a security/production-stability regression, NOT "a larger diff is
125 + riskier";
126 + - (c) confirmed by the user as outside the approved scope; or
127 + - (d) accepted by the user, through the Mandatory pause, as an in-scope
128 + partial to ship now.
129 +
130 + For (a)/(b) you MUST cite specific evidence (file/line, failure class, or
131 + test) and route through the Mandatory pause — you do not self-certify
132 + "unsafe." For (d) track the remainder per "Followup Discipline" with why
133 + deferral is acceptable and when it lands; repeatedly shipping partials is
134 + debt accumulation, not delivery. Risk reduction, review convenience, smaller
135 + diff, and issue staging are NEVER valid and MUST NOT be relabeled "unsafe"
136 + or "independent."
137 + - Mandatory pause: if the delivered state will fall short of its recorded
138 + target for any reason other than approved staged delivery, you MUST present
139 + the evidence, STOP, and obtain explicit user approval (see Approval bar)
140 + before proceeding, before requesting non-draft review, and before marking
141 + the work complete.
142 + - Approval bar (used by every gate): approval means the user explicitly
143 + accepts a trade-off, goal, or plan that you stated in your own words (what
144 + stays redundant or partial, and why). A bare "ok" or "sounds good" to a
145 + one-sided pitch is not approval.
146 + - Re-evaluation: at the completion of each planned step, before opening or
147 + updating a PR, and before marking a SOW completed (the Re-evaluation
148 + checkpoints), you MUST re-evaluate already-written changes against the
149 + recorded target; you SHOULD also re-evaluate whenever you pause to report
150 + progress. Do not keep a compromise only because it already exists in the
151 + branch.
152 + - Staged delivery: allowed ONLY when every stage is an in-scope decomposition
153 + of one approved clean end state and the stages together reach it. The user
154 + approval recorded for the staged plan covers the intermediate states, so an
155 + approved stage does not re-trigger the Mandatory pause; every later stage
156 + MUST be tracked per "Followup Discipline" (implemented here, rejected with
157 + evidence, or a linked GitHub issue) before an earlier stage merges. A
158 + self-certified "a later stage will finish it" with no tracked item is not
159 + acceptable.
160 + - Deferral check: before recommending deferral, check the issue, SOW,
161 + acceptance criteria, and affected migration scope. Silence or ambiguity MUST
162 + NOT be read as permission to defer; if those sources do not clearly place
163 + the work outside the approved clean end state, treat it as in-scope and
164 + either complete it or pause for a user decision.
165 + - Trivial-work exemption: trivial work (per "When A SOW Is Required") has no
166 + SOW and is exempt from the record-the-target, disclosure, and
167 + reference-search bullets above; the clean-end-state preference still applies.
168 + When unsure, treat the work as non-trivial.
169 +
170 +2. **Plan before non-trivial work.**
171 + - Plan first: non-trivial work (see "When A SOW Is Required") MUST start with
172 + a plan recorded in the SOW before any implementation-file change and before
173 + any implementation-equivalent action — migrations, deletions, pushes,
174 + non-draft PRs, or external-state mutations via tools. Trivial work is exempt;
175 + when unsure, treat the work as non-trivial.
176 + - Human-owned goal: the desired end state — the goal, or coherent goal set, the
177 + work must reach — MUST be created with or approved by the user. You MUST NOT
178 + finalize the goal unilaterally (same user-owned target as Clean end state).
179 + - End state first: you MUST establish the desired end state — including its
180 + acceptance criteria — before planning the steps; the goal drives the work,
181 + not a first diff. If you cannot yet state the end state, keep investigating
182 + until you can; do not start work against an unknown target. When the end
183 + state is itself a user-owned design decision, record a provisional target
184 + plus the open question and resolve it with the user first (Clean end state).
185 + Then plan the steps to move from the current state toward that end state.
186 + - Decompose into steps: split the work into ordered steps, each with its own
187 + clean end state and acceptance criteria, each building on the previous one
188 + toward the desired end state. A single coherent step is a valid decomposition
189 + when the work is atomic; do not invent artificial sub-steps.
190 + - Resolve huge or vague work: if the deliverable is large or vague, keep
191 + refining the plan until every step has a clean end state and acceptance
192 + criteria. Do not start implementation while steps are still unclear.
193 + - Reachability: the plan MUST either reach the desired end state through its
194 + steps, or produce evidence that it is not achievable; an unachievable goal
195 + is a pause condition for a user decision, not a silent partial result.
196 + - Human approval gate: when a goal-approval round is required (see "Approval is
197 + for goal-decisions" below), the whole plan — the desired end state and the
198 + step breakdown — MUST be explicitly approved by the user before
199 + implementation. The assistant proposes and investigates; the user approves.
200 + State the goal and step breakdown being accepted, and get confirmation that
201 + meets the Approval bar (Clean end state). If the user rejects or edits the
202 + plan, revise and re-seek approval; the SOW stays in `planning` until an
203 + explicit approval is recorded, then reaches `Status: ready`. This gate is the
204 + canonical statement of the approval requirement that the Pre-Implementation
205 + Gate and Required First Checks reference.
206 + - Approval is for goal-decisions, not work categories:
207 + - The goal-approval round fires ONLY when the end state is a genuine
208 + user-owned fork — competing designs, a public-contract change, a
209 + destructive or irreversible step, or unclear scope.
210 + - Other non-trivial work whose end state is already fixed by the triggering
211 + request, an existing project skill, or an established repository pattern
212 + (for example a clear bug fix, a metadata/docs edit with no contract change,
213 + or a collector's skeleton and wiring fixed by its authoring skill — though
214 + its Function surface, vnode/host-scope design, and new public config
215 + options remain user-owned forks) still needs a recorded plan and the
216 + Pre-Implementation Gate, but the triggering request IS the recorded goal
217 + approval — no separate round, which also satisfies the resume re-check and
218 + the progress rule.
219 + - When it is unclear whether a real fork exists, treat it as user-owned and
220 + seek approval.
221 + - Approval persists; re-check on resume: before continuing an `in-progress` or
222 + `paused` SOW you did not personally take through this gate — including
223 + takeover or handoff — you MUST confirm the SOW records explicit approval of
224 + the current goal and plan. If it does not, or the plan changed materially
225 + since approval, treat the SOW as `planning` and re-obtain approval before
226 + further implementation.
227 +
228 +3. **Scope discipline at every step.**
229 + - Drift check: at each Re-evaluation checkpoint (Clean end state), you MUST
230 + also check whether the work has drifted outside the approved scope, not only
231 + whether the diff still matches the recorded target.
232 + - Independence test: new work is "genuinely independent" only if ALL hold —
233 + (a) the approved clean end state is still complete and correct without it,
234 + (b) it is not a coupled item or a remaining reference recorded under Clean
235 + end state, and (c) it has its own separable acceptance criteria. If any test
236 + fails, or you are unsure, treat the work as coupled, not independent, and
237 + handle it under Clean end state (do the low-risk part and disclose it; pause
238 + only for a genuine fork) — you are not the scope authority.
239 + - Disposition of independent work:
240 + - Do NOT silently bundle it.
241 + - Submit it as a separate PR first and rebase the current branch after it
242 + merges, or track it as a GitHub issue per "Followup Discipline."
243 + - Do NOT fold it into this SOW's steps — Clean-end-state staged-delivery
244 + stages must be a decomposition of one clean end state.
245 + - Governed elsewhere: coupled cleanup is in scope (Clean end state), and
246 + non-trivial work is delivered in coherent incremental steps (Plan before
247 + non-trivial work); this principle does not restate them.
248 +
249 +**Flow diagrams (human reading aid, non-normative):** the bullets above are
250 +authoritative; the diagrams below summarize the flow for human readers and MUST
251 +be kept in sync when the principles change.
252 +
253 +<details>
254 +<summary>Show per-principle flow diagrams</summary>
255 +
256 +How the three principles connect (lifecycle order):
257 +
258 +```mermaid
259 +flowchart LR
260 + A("1. Clean end state<br/>defines the target (what 'done' means)")
261 + B("2. Plan before non-trivial work<br/>establish the target + steps; user approves real forks")
262 + C("3. Scope discipline<br/>stay on the target while executing each step")
263 + A --> B --> C
264 + C -->|re-evaluate vs target| A
265 +```
266 +
267 +1. Clean end state over less churn:
268 +
269 +```mermaid
270 +flowchart TD
271 + A("Approved scope = issue + SOW Purpose/Acceptance + implied surface")
272 + B("Define the clean end state, incl. removing what the change makes redundant")
273 + C("Record target in SOW: exclusions list + reference search if a path/contract is replaced")
274 + D{"Matches recorded target?"}
275 + E("Deliver the clean end state")
276 + F{"Allowed exception?"}
277 + Fx("Only: a) impossible, b) evidenced safety risk, c) out of scope, d) user-accepted partial")
278 + G("NOT allowed: risk reduction, smaller diff, or staging")
279 + H("Mandatory pause: present evidence, STOP")
280 + I{"Explicit approval?"}
281 + Ix("Approval bar: a bare 'ok' is not approval")
282 + J("Proceed; track remainder per Followup Discipline")
283 + K("Re-evaluate vs target: each step, before a PR, before complete")
284 + A --> B --> C --> D
285 + D -->|yes| E
286 + D -->|no| F
287 + F -->|no| G --> B
288 + F -->|yes| H --> I
289 + I -->|no| B
290 + I -->|yes| J
291 + F -.- Fx
292 + I -.- Ix
293 + E --> K
294 + J --> K
295 +```
296 +
297 +2. Plan before non-trivial work:
298 +
299 +```mermaid
300 +flowchart TD
301 + A("Task")
302 + B{"Trivial?"}
303 + C("Exempt: just do it (clean-end-state preference still applies)")
304 + D("Establish the desired end state + acceptance criteria FIRST; keep investigating until you can")
305 + E("Decompose into ordered steps, each with its own clean end state + criteria; move current toward desired")
306 + F{"End state a user-owned fork?"}
307 + Fk("Fork = competing designs, public-contract/destructive change, or unclear scope")
308 + G("Fixed by request/skill/pattern: the request IS the approval (recorded plan + gate, no separate round)")
309 + H("Goal-approval round: explicit user approval of the whole plan (Approval bar)")
310 + I("Status: ready, implement")
311 + J("Pause for a user decision (not a silent partial)")
312 + A --> B
313 + B -->|yes| C
314 + B -->|no| D
315 + D --> E --> F
316 + F -->|no| G
317 + F -->|yes| H
318 + F -.- Fk
319 + G --> I
320 + H --> I
321 + D -->|goal unreachable| J
322 +```
323 +
324 +3. Scope discipline at every step:
325 +
326 +```mermaid
327 +flowchart TD
328 + A("At each Re-evaluation checkpoint")
329 + B{"Drifted outside approved scope?"}
330 + C("Continue")
331 + D{"Genuinely independent?"}
332 + Dx("Independent only if ALL: end state complete without it; not a coupled item/reference; separable acceptance criteria")
333 + E("Treat as COUPLED: handle under Clean end state (do the low-risk part + disclose); pause only for a genuine fork")
334 + F("Do NOT bundle silently: separate PR + rebase, or track as a GitHub issue; never fold into this SOW's steps")
335 + A --> B
336 + B -->|no| C
337 + B -->|new work| D
338 + D -->|no or unsure| E
339 + D -->|yes| F
340 + D -.- Dx
341 +```
342 +
343 +</details>
344
345 USER COMMUNICATION:
346
@@ -65,11 +361,16 @@ Project SOW status: initialized
361
362 This project uses a local Statement of Work system.
363
68 -SOWs are branch-local working memory, not product artifacts. A SOW lives on the
69 -feature branch for the duration of the work so it preserves the root-cause
70 -model, decisions, evidence, and validation for PR takeover. It is removed before
71 -the branch merges. `master` MUST contain no SOW working files; durable memory
72 -belongs in `.agents/sow/specs/`, project skills, docs, code, and tests.
364 +SOWs are branch-local working memory, not product artifacts. During active work,
365 +including draft PR and ready-for-review takeover work, a SOW may live on the
366 +feature branch so it preserves the root-cause model, decisions, evidence, and
367 +validation for PR takeover. Commit the active SOW on the feature branch when
368 +takeover or handoff is expected. When no takeover is expected, keeping the
369 +active SOW local and uncommitted is acceptable, but the SOW still MUST be used
370 +as working memory. Before merge, complete the SOW, transfer durable knowledge,
371 +and delete the active SOW file. `master` and the final merge head MUST contain
372 +no SOW working files; durable memory belongs in `.agents/sow/specs/`, project
373 +skills, docs, code, and tests.
374
375 The SOW system is self-contained in this repository. Normal SOW work must not depend on `~/.agents`, `~/.AGENTS.md`, global skills, global templates, or global scripts. Use this `AGENTS.md`, the branch-local SOW, project-local specs, and project-local skills.
376
@@ -87,7 +388,7 @@ Before non-trivial work:
388 3. Inspect `.agents/skills/*/SKILL.md` if any exist, and load every runtime project skill whose trigger matches the work.
389 4. Inspect legacy runtime skills listed below when the user request matches their frontmatter trigger.
390 5. Inspect code, docs, tests, and existing project instructions as ground truth.
90 -6. Ask the user only for irreducible product/design/risk decisions.
391 +6. Ask the user only for irreducible product/design/risk decisions. For non-trivial work, the goal and plan are user-owned decisions gated by the "Plan before non-trivial work" Human approval gate.
392
393 ### Git Worktrees
394
@@ -108,6 +409,37 @@ Write only sanitized evidence:
409
410 If sensitive data is required to continue, stop and ask the user for a secure handling path. If sensitive data is found in a durable artifact, sanitize it before any commit. If sensitive data was already committed, tell the user and do not rewrite history without explicit approval.
411
412 +### Durable AI-Facing Artifact Formatting
413 +
414 +AI-facing durable artifacts include `AGENTS.md`, SOW specs, runtime project
415 +skills, public/operator skills, SOW templates, instruction bridge files, and
416 +other docs primarily written so future AI agents can execute repository rules
417 +correctly.
418 +
419 +When writing or updating these artifacts:
420 +
421 +- Structure for retrieval and scanning. Use headings, short sections, labeled
422 + bullets, and numbered procedures so both humans and AI agents can find the
423 + exact rule quickly.
424 +- Avoid dense multi-rule paragraphs. If a paragraph contains multiple
425 + requirements, exceptions, or decision branches, split it into bullets or a
426 + table.
427 +- Use tables only for matrices or comparisons where the cells stay short. Use
428 + bullets for rules, workflows, checklists, and exception handling.
429 +- Put RFC-style requirement words (`MUST`, `MUST NOT`, `SHOULD`, `MAY`) close
430 + to the action they govern. Do not hide mandatory behavior in explanatory
431 + prose.
432 +- Prefer labeled bullets for operational guardrails, such as `Target`,
433 + `Exception handling`, `Validation`, or `Failure mode`.
434 +- Keep one durable idea per bullet. If a bullet needs multiple sentences, the
435 + first sentence states the rule and later sentences provide evidence,
436 + rationale, or examples.
437 +- For a guardrail with several distinct requirements, use a labeled parent
438 + bullet with an indented sub-list — one requirement per sub-bullet — rather than
439 + a multi-requirement paragraph; keep a single rule-plus-rationale as one bullet.
440 +- Preserve precision over brevity. Formatting is for readability, not for
441 + weakening contracts or removing necessary evidence.
442 +
443 ### Open-Source Reference Evidence
444
445 When SOW evidence comes from other open-source repositories, cite the upstream repository and checked commit instead of the workstation absolute path.
@@ -123,9 +455,9 @@ Resolve `owner/repo` from the repository remote, record the checked commit, and
455
456 ### Pre-Implementation Gate
457
126 -Implementation must not begin until the branch-local SOW contains a concrete `## Pre-Implementation Gate` section with `Status: ready` or `Status: in-progress`. Before changing implementation files, or before continuing implementation in an existing SOW that lacks this section, fill the gate.
458 +Implementation must not begin until the branch-local SOW contains a concrete `## Pre-Implementation Gate` section with `Status: ready` or `Status: in-progress`. Before changing implementation files, or before continuing implementation in an existing SOW that lacks this section, fill the gate. Reaching `Status: ready` additionally requires the "Plan before non-trivial work" Human approval gate (explicit user approval of the goal and plan).
459
128 -The gate must record the problem/root-cause model, evidence reviewed, affected contracts and surfaces, existing patterns to reuse, risk and blast radius, sensitive data handling plan, implementation plan, validation plan, artifact impact plan, and open decisions. The sensitive data plan must cover SOWs, specs, documentation, project skills, agent instructions, and code comments. Generic placeholders such as `TBD`, `N/A`, or "to be checked later" are invalid unless the SOW explains why the item truly does not apply. If the gate exposes an unknown that cannot be resolved by investigation, stop and ask the user before implementation.
460 +The gate must record the problem/root-cause model, evidence reviewed, affected contracts and surfaces, the clean-end-state target (its removed-redundant and excluded-coupled items, and the reference search where a path or contract is replaced), existing patterns to reuse, risk and blast radius, sensitive data handling plan, implementation plan, validation plan, artifact impact plan, and open decisions. The sensitive data plan must cover SOWs, specs, documentation, project skills, agent instructions, and code comments. Generic placeholders such as `TBD`, `N/A`, or "to be checked later" are invalid unless the SOW explains why the item truly does not apply. If the gate exposes an unknown that cannot be resolved by investigation, stop and ask the user before implementation.
461
462 ### When A SOW Is Required
463
@@ -151,7 +483,7 @@ Trivial work does not need a SOW:
483 - typo fixes;
484 - formatting-only changes;
485 - mechanical rename with no behavior change;
154 -- simple search/replace with low risk.
486 +- simple search/replace with low risk (still grep for the old token to confirm no call sites are missed).
487
488 When unsure, treat the work as non-trivial.
489
@@ -164,7 +496,8 @@ When unsure, treat the work as non-trivial.
496
497 There is no `done/` directory and no committed pending queue. On `master`,
498 `.agents/sow/active/` is empty except for `.gitkeep`; real SOW files exist only
167 -on feature branches and are deleted before merge.
499 +on feature branches. Feature branches and PRs may commit active SOW files when
500 +takeover or handoff is expected, but active SOW files are deleted before merge.
501
502 Create new SOW files from `.agents/sow/SOW.template.md`. The template is project-local and may be customized for this repository.
503
@@ -191,8 +524,9 @@ Deferred work has two valid tracking paths:
524 - public or team-visible follow-up: GitHub issue;
525 - private or local follow-up: `<repo-root>/.local/sow/`.
526
194 -Active implementation work still MUST use `.agents/sow/active/`, and active SOW
195 -files still MUST be deleted before merge.
527 +Active implementation work still MUST use `.agents/sow/active/`. Active SOW
528 +files MAY be committed for takeover or handoff and still MUST be deleted before
529 +merge.
530
531 Filename:
532
@@ -206,7 +540,7 @@ counter because it cannot be allocated safely across parallel branches.
540 SOW state lives in the file's `Status:` field:
541
542 - `planning` - analysis or decisions are incomplete; implementation is blocked.
209 -- `ready` - the Pre-Implementation Gate is complete and implementation can start.
543 +- `ready` - the Pre-Implementation Gate is complete and, where the goal-approval round ("Plan before non-trivial work") applies, the user has approved the goal and plan; implementation can start.
544 - `in-progress` - implementation is underway.
545 - `paused` - work is intentionally stopped but may resume on the branch.
546 - `completed` - work is validated and durable memory has been transferred; this is a transient state before deleting the SOW file.
@@ -222,7 +556,11 @@ When a SOW's work is ready to merge:
556 3. Update the SOW to `Status: completed`.
557 4. Delete the SOW working file before merge.
558
225 -The branch HEAD that merges MUST contain no `.agents/sow/active/SOW-*.md` file. CI enforces this.
559 +Draft and ready-for-review PRs MAY temporarily contain
560 +`.agents/sow/active/SOW-*.md` files when takeover or handoff is expected. The
561 +SOW CI job still rejects committed active SOW files; that red check is an
562 +intentional merge guard, not a sign that handoff or takeover is forbidden. The
563 +branch HEAD that merges MUST contain no `.agents/sow/active/SOW-*.md` file.
564
565 ### Enforcement
566
@@ -234,7 +572,9 @@ The SOW system is enforced by local audit tooling and CI:
572 local audit and CI.
573 - `.github/workflows/sow.yml` rejects pull requests that contain branch-local
574 SOW working files under `.agents/sow/active/SOW-*.md` or legacy SOW working
237 - files under `.agents/sow/{pending,current,done}/SOW-*.md`.
575 + files under `.agents/sow/{pending,current,done}/SOW-*.md`. This failure is
576 + expected when an active SOW is intentionally committed for takeover or
577 + handoff; it MUST be cleared before merge.
578 - The same workflow scans changed SOW, spec, instruction, and cross-tool
579 bridge files for raw sensitive data.
580
@@ -252,7 +592,7 @@ If work overlaps:
592 - merge or consolidate branches before implementation; or
593 - split into separate SOWs and complete one before starting the next.
594
255 -Progress reports are not stop points. Once a SOW is in progress, continue until it is delivered, failed with evidence, blocked on a real user decision/approval, or superseded by newer user instructions.
595 +Progress reports are not stop points (re-evaluating against the target per the Clean-end-state rule is not itself a stop point). Once a SOW is in progress and its goal/plan approval is recorded ("Plan before non-trivial work"), continue until it is delivered, failed with evidence, blocked on a real user decision/approval, or superseded by newer user instructions.
596
597 ### User Decisions
598
@@ -262,7 +602,7 @@ When user decisions are needed:
602 2. Provide numbered options.
603 3. Explain pros, cons, implications, and risks.
604 4. Recommend one option with reasoning.
265 -5. Record the user's decision in the SOW before implementation.
605 +5. Record the user's decision in the SOW before implementation. For the goal/plan approval round, the bar is the "Plan before non-trivial work" Human approval gate.
606
607 ### Followup Discipline
608
@@ -304,6 +644,8 @@ Do not attempt to resurrect or mutate a prior SOW.
644 A SOW cannot be completed until Validation records:
645
646 - acceptance criteria evidence;
647 +- clean-end-state evidence: the delivered state matches the clean end state recorded in the SOW, including its recorded list of removed-redundant and excluded coupled items (and, where a path or contract was replaced, the recorded reference search), or an explicit user approval for a non-clean state is recorded and linked;
648 +- deferred clean-end-state remainder: any clean-end-state work deferred under an approved partial (exception (d)) or otherwise tracked rather than done is listed with why deferral was acceptable and when (or under what condition) it lands;
649 - tests or equivalent validation;
650 - real-use evidence when a runnable path exists;
651 - reviewer findings and how they were handled;