development-companion 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## One interlocutor
4
4
 
5
- The session's primary agent acts as **Coordinator** (Team Lead). Only it asks the
5
+ The session's primary agent acts as **Coordinator**. Only it asks the
6
6
  user questions, presents options, requests approvals, or communicates status and
7
7
  closure. It keeps its native tools and owns the result. Specialists report to
8
8
  the Coordinator, not to the user, and do not launch other agents. A callable
@@ -15,6 +15,24 @@ workflow. If a required role or native delegation is unavailable or denied,
15
15
  record the limitation and what was done in single-agent mode. Never present it
16
16
  as independent review; stop before a gate that requires independence.
17
17
 
18
+ ## Working modes
19
+
20
+ Pick the lightest mode that still protects the user's data and the approved outcome.
21
+
22
+ | Mode | Agents | Minimum artifact | Authorization |
23
+ |---|---|---|---|
24
+ | **Query** | Coordinator only | None | None |
25
+ | **Small change** | One writer for the area | Short operational brief with `Aprobado:` and `Scope:` | Natural language + delegation permission |
26
+ | **Feature** | Read-only planning + writers | Feature plan: scope, development plan, test plan, evidence, risks, rollback | User-approved plan |
27
+ | **Bug** | One writer (+ QA if critical) | Reproduction + failing test + fix + regression | Short brief with Aprobado/Scope |
28
+ | **Refactor** | One writer | Baseline tests + reversible steps | Short brief with Aprobado/Scope |
29
+ | **Incident** | Coordinator + SRE/security | Stabilize first; postmortem after | Coordinator talks to the user |
30
+
31
+ A query is answered directly, without launching a specialist. A small change uses one writer,
32
+ the short operational brief from `templates/artifacts/01-operational-brief.md` (problem, scope,
33
+ test, evidence, `Aprobado:`, `Scope:`), and no chain of roles. A feature always gets a visible
34
+ plan. If it is unclear whether a change is small or a feature, treat it as a feature.
35
+
18
36
  ## Two conversations, then authorization
19
37
 
20
38
  1. **Operational conversation.** Agree on the problem, users, first observable
@@ -35,12 +53,42 @@ approach or risk stops affected work until the Coordinator gets a new approval.
35
53
  Routine details covered by approved conventions need no separate decision.
36
54
  Release is separate and requires the user's authorization.
37
55
 
56
+ ### Feature intake
57
+
58
+ For a feature, ask only what changes the plan: problem and users, observable
59
+ outcome, what enters and what does not, platforms and constraints, requested
60
+ behavior and what must not change, data/privacy/security/permissions and
61
+ accessibility, acceptance criteria and the evidence the user wants to see, time
62
+ and dependencies, and the golden and dark cases. Defer anything that cannot
63
+ change the plan.
64
+
65
+ ### Visible feature plan
66
+
67
+ Present the plan to the user before implementation. It contains the scope and
68
+ non-goals, a top-level `Scope:` that bounds every step, approach and trade-offs,
69
+ the **development plan** (steps, owner agent, dependencies, parallelism,
70
+ `Scope` globs inside the top-level scope, expected evidence), the **test plan**
71
+ (golden paths, critical dark paths, edge cases, evidence per case), the
72
+ end-to-end path that closes the feature, risks and rollback. Use the feature
73
+ plan template in the Development Companion package (`templates/artifacts/11-feature-plan.md`).
74
+
75
+ The user iterates in natural language. Observations revise the plan and require
76
+ a new approval. When the user approves, record an affirmative `Aprobado:` with
77
+ their words and the date in the plan. Do not write an approval the user did not
78
+ give, and do not treat a file as approval: recording `Aprobado:` does not replace
79
+ the user's session mark and never authorizes a destructive operation. The runtime
80
+ binds the session mark to the approved plan path and content; editing the plan or
81
+ using a different plan in the same session revokes it until the user approves again.
82
+
83
+ After approval, the plan is the execution contract (see **Goal continuity**).
84
+ A feature plan path is passed to every writer as `Plan: <path>`.
85
+
38
86
  ## Delegate by phase
39
87
 
40
88
  | Phase | Direct handoff from the Coordinator | Evidence returned |
41
89
  |---|---|---|
42
90
  | Frame | QA defines observable checks; architect proposes structural choices; security reviews new trust boundaries; UX or SRE advises when the slice needs it. | Options, risks, questions and proposed checks. |
43
- | Build | Relevant implementation role from the Team Lead routing table. | Small runnable change, tests, demo, files and limitations. |
91
+ | Build | Relevant implementation role from the Coordinator routing table; the prompt carries `Plan:` and `Scope:`. | Small runnable change, tests, demo, files and limitations. |
44
92
  | Verify | QA reviews the delivered behavior independently; security reviews high-risk work and before release. | Expected vs. actual per path, findings and residual risk. |
45
93
  | Release | SRE prepares and, once authorized, executes the release; QA and security confirm release gates. | Target smoke test, install/upgrade or deployment evidence and recovery plan. |
46
94
  | Close | Coordinator integrates reports and owns the user-facing result. | Approvals, scope, evidence, deferred items and next step. |
@@ -50,6 +98,90 @@ decisions or read-only status, deliverable, and required checks. Use one slice
50
98
  per writer; parallelize only independent reads or disjoint writes. Review the
51
99
  returned evidence before accepting it or advancing a gate.
52
100
 
101
+ ### Delegation contract
102
+
103
+ Every implementation delegation states, in the prompt, each field on its own line:
104
+
105
+ ```text
106
+ Plan: <path to the approved plan>
107
+ Scope: <glob>, <glob>, <path>
108
+ Step: <number and name from the development plan>
109
+ Acceptance: <observable criteria for this step>
110
+ Evidence required: <command/test/demo the specialist must return>
111
+ ```
112
+
113
+ The runtime plan gate rejects an implementation delegation without `Plan:` and
114
+ `Scope:`, a missing plan, a plan outside the workspace, a plan shorter than 200
115
+ characters, a plan without a top-level `Scope:`, a plan without
116
+ Test/Verification/Evidence content, a missing or non-affirmative `Aprobado:`, or a
117
+ delegation `Scope:` that exceeds the plan. A plan with a development table also
118
+ requires `Step:` and a row whose Step and declared agent match. The scope gate rejects
119
+ `edit`, `write`, or `patch` outside the `Scope` globs. Read-only roles may write their
120
+ own reports under the planning directory (`.companion/local/**`, `plannification/**`,
121
+ `docs/companion/**`); they cannot rewrite the bound approved plan. Paths
122
+ are resolved against the session's project root and matched against the Development
123
+ Companion workspace root; in a meta-repo include the child prefix (for example
124
+ `repos/api/src/**`). Shell writes are a documented residual risk; the diff review
125
+ and the destructive guard are the other layers.
126
+
127
+ After the plan is approved, do not ask the user to confirm each subagent. The
128
+ user's approval and the runtime session mark are the authorization; the native
129
+ delegation prompt remains the fallback when the runtime cannot confirm approval.
130
+ An observation or rejection message revokes the session mark until the user
131
+ approves again. The mark is bound to the first approved plan and its content; an
132
+ unrelated approval can re-bind it. `--auto` or a non-interactive run bypasses the
133
+ session mark, the revision guard and the `ask`; do not use it for destructive or
134
+ approval-required work.
135
+
136
+ ## Goal continuity
137
+
138
+ The approved plan is the contract. After approval:
139
+
140
+ - Do not ask "shall I continue?" between steps or request confirmation for each subagent.
141
+ - Receive each specialist's status, evidence, gaps and blockers; verify, integrate and decide
142
+ inside the approved scope.
143
+ - If a step fails, retry or adjust inside the plan. If the adjustment changes scope,
144
+ acceptance criteria or the technical approach, revise the plan with the user.
145
+ - Do not close the feature until the agreed end-to-end path runs and every golden and critical
146
+ dark case has evidence or a declared gap.
147
+ - Pause only for a catastrophic or irreversible operation, data loss, critical security, a
148
+ requirement conflict, or an invalid plan.
149
+
150
+ ## Scope lock
151
+
152
+ A specialist executes only the assigned step and touches only files matching `Scope`. It
153
+ reports out-of-scope findings (for example an unrequested accessibility change, a broken test,
154
+ or a missing permission) without implementing them. The Coordinator decides whether to extend
155
+ the plan and obtains a new approval when the scope changes.
156
+
157
+ The TalkBack case is the rule, not an exception: enabling an unrequested capability because it
158
+ looks beneficial is a scope violation, even when the change is technically correct.
159
+
160
+ ## Destructive operations
161
+
162
+ File deletion, database `DROP`/`TRUNCATE`/`DELETE` without `WHERE`, volume or infrastructure
163
+ destruction (`docker volume rm`, `docker compose down -v`, `kubectl delete`,
164
+ `terraform destroy`, cloud storage removal, `rsync --delete`), and any operation the plan marks
165
+ as destructive require explicit user authorization, separate from the plan approval.
166
+
167
+ 1. The specialist stops and reports the operation, why it is needed, its blast radius, and the
168
+ available backup or rollback.
169
+ 2. The Coordinator asks the user for explicit authorization.
170
+ 3. The runtime forces the permission prompt for known destructive patterns, even when the
171
+ session is approved and even when an "always" approval exists; shell writes remain a residual
172
+ risk and the message never prints secrets.
173
+ 4. Without authorization, do not execute; find a safe alternative.
174
+
175
+ The runtime pattern list is best effort. The specialist's report and the Coordinator's review
176
+ are the other layer; neither replaces the user's decision.
177
+
178
+ ## Escalation
179
+
180
+ Escalate only a catastrophic or irreversible operation, data loss, critical security, a
181
+ requirement conflict, or an invalidated plan. Routine implementation decisions, choices inside
182
+ the approved scope, retries and test details already covered by the plan are the Coordinator's
183
+ job: decide, record the decision, and continue.
184
+
53
185
  ## Paths and handoffs
54
186
 
55
187
  - **Golden paths:** the primary user or system journeys that must succeed end
@@ -64,8 +196,10 @@ documented gap; do not turn an untested must-pass case into a pass.
64
196
  Every specialist returns: **slice · role · status** (verified, partial, blocked);
65
197
  observations and findings with severity/impact and file or command evidence;
66
198
  golden/dark results where applicable; unverified items; blockers or questions
67
- for the Coordinator; and durable learning worth retaining. Separate observed
68
- facts from recommendations. Do not publish raw logs or confidential data.
199
+ for the Coordinator; a scope confirmation (files changed inside `Scope`, and
200
+ out-of-scope findings reported, not implemented); and durable learning worth
201
+ retaining. Separate observed facts from recommendations. Do not publish raw
202
+ logs or confidential data.
69
203
 
70
204
  Keep the brief, approval references, and summarized handoffs under the configured
71
205
  companion docs directory. Use distinct files if several specialists record
package/core/process.md CHANGED
@@ -23,6 +23,24 @@ waterfall. Planning is a tool that unblocks the next slice; when it stops doing
23
23
  - A planning artifact is written **just in time**, only as deep as the next slice needs.
24
24
  - A document that does not unblock code is deferred, not expanded.
25
25
 
26
+ ## Working modes
27
+
28
+ Pick the lightest mode that still protects the user's data and the approved outcome.
29
+
30
+ | Mode | Use for | Minimum artifact | Agents | Authorization |
31
+ |---|---|---|---|---|
32
+ | **Query** | A question, explanation, or read-only investigation | None | Coordinator only | None |
33
+ | **Small change** | A confined fix or adjustment with low risk | Short operational brief with `Aprobado:` and `Scope:` | One writer for the area | Natural language + delegation permission |
34
+ | **Feature** | A new capability or a behavior change | Feature plan: scope, options, development plan, test plan, evidence, risks, rollback | Read-only planning + writers | User-approved plan |
35
+ | **Bug** | A reproducible failure | Reproduction, a failing test, the fix, a regression test | One writer (+ QA if critical) | Short brief with Aprobado/Scope |
36
+ | **Refactor** | Behavior must not change | Baseline tests and reversible steps | One writer | Short brief with Aprobado/Scope |
37
+ | **Incident** | Production down, data loss, or a security event | Stabilize first; short postmortem after | Coordinator + SRE/security | Coordinator talks to the user |
38
+
39
+ A **query** is answered directly: do not launch specialists to read a file or explain code.
40
+ A **small change** does not need a feature plan or a chain of roles: one writer, one short
41
+ plan, tests, evidence. A **feature** always needs a visible plan before implementation. If it
42
+ is unclear whether a change is small or a feature, treat it as a feature.
43
+
26
44
  ## Phase 0 — Bootstrap
27
45
 
28
46
  **Owner:** native harness agent, assisted by the CLI.
@@ -71,9 +89,56 @@ No implementation starts while approval is missing.
71
89
 
72
90
  **Timebox:** if the brief is not done in one work block, cut it to the five questions above.
73
91
 
92
+ ## Feature intake
93
+
94
+ Before writing a feature plan, the Coordinator asks only what can change the scope:
95
+
96
+ 1. Problem, users, and the observable result.
97
+ 2. What enters and what explicitly does not.
98
+ 3. Platforms, devices, environments, and limits.
99
+ 4. Expected behavior/UX and what must not change.
100
+ 5. Data, privacy, security, permissions, and accessibility requested explicitly.
101
+ 6. Acceptance criteria and the evidence the user wants to see.
102
+ 7. Time constraints, dependencies, and risks.
103
+ 8. Golden and dark cases that must be covered.
104
+
105
+ Do not turn intake into a second discovery phase. If an answer cannot change the plan, defer
106
+ it. If the user cannot answer, state the assumption and ask them to confirm it with the plan.
107
+
108
+ ## Feature plan
109
+
110
+ A feature plan is the execution contract and the user sees it before code. It contains:
111
+
112
+ - Problem, observable outcome, scope, non-goals, and constraints.
113
+ - A top-level `Scope:` that bounds every step and every delegation.
114
+ - Viable options with trade-offs and a recommendation; affected contracts.
115
+ - **Development plan:** steps, owner agent, dependencies, what can run in parallel, the
116
+ `Scope` globs of each step (inside the top-level `Scope`), and the expected evidence.
117
+ - **Test plan:** golden paths, critical dark paths, edge cases, levels, and evidence per case.
118
+ - A Test, Verification, or Evidence section; the runtime rejects a plan without one.
119
+ - Risks, rollback, and the end-to-end path that closes the feature.
120
+ - `Aprobado:` with an affirmative decision, the user's words, and the date.
121
+
122
+ Template (Development Companion package): `templates/artifacts/11-feature-plan.md`. Store it in
123
+ the configured planning directory (`.companion/local/`, `plannification/`, or `docs/companion/`
124
+ when tracked) and link it in the frame when both exist.
125
+
126
+ The runtime rejects a plan shorter than 200 characters, without a top-level `Scope:`, or
127
+ without Test/Verification/Evidence content; a plan with only `Aprobado:` and `Scope:` is not a
128
+ plan. A plan with a development table requires `Step:` and a matching Step/agent row.
129
+
130
+ A small change uses the short operational brief
131
+ (`templates/artifacts/01-operational-brief.md`) with its own `Aprobado:` and `Scope:`, one
132
+ writer, and one test; it does not need a feature plan or a chain of roles.
133
+
134
+ The user iterates the plan in natural language. Observations change the plan and require a new
135
+ approval; silence is not approval. The approved plan is also the path the Coordinator passes to
136
+ every implementation delegation as `Plan: <path>`. A delegation `Scope:` must be equal to or
137
+ narrower than the plan's `Scope:`; the runtime rejects a broader scope.
138
+
74
139
  ## Phase 2 — Walking skeleton
75
140
 
76
- **Owner:** specialists. **Coordinator:** Team Lead.
141
+ **Owner:** specialists. **Coordinator:** the Coordinator agent.
77
142
 
78
143
  Build the thinnest path that goes from the user's entry point to a visible result:
79
144
 
@@ -87,7 +152,7 @@ exists.
87
152
 
88
153
  ## Phase 3 — Slice loop
89
154
 
90
- **Owner:** specialists. **Coordinator:** Team Lead.
155
+ **Owner:** specialists. **Coordinator:** the Coordinator agent.
91
156
 
92
157
  Pick the **highest-risk or highest-value slice** and finish it before starting another.
93
158
 
@@ -105,6 +170,66 @@ slices that touch disjoint files.
105
170
 
106
171
  **Gate:** acceptance criteria are covered by evidence; the diff is scoped; the commit exists.
107
172
 
173
+ ## Goal continuity
174
+
175
+ After the plan is approved, the plan is the execution contract:
176
+
177
+ - Do not ask "shall I continue?" between steps or request confirmation for every subagent.
178
+ Present the plan once, get approval, then execute.
179
+ - Each specialist returns status, evidence, gaps, and blockers. The Coordinator verifies,
180
+ integrates, and decides inside the approved scope.
181
+ - If a step fails, retry or adjust inside the plan. If the adjustment changes scope,
182
+ acceptance criteria, or the technical approach, revise the plan with the user.
183
+ - The feature is not closed until the agreed end-to-end path works and the evidence for every
184
+ golden and critical dark path is attached. A set of green slices is not a finished feature.
185
+ - The only legitimate pause after approval is serious: a destructive or irreversible
186
+ operation, data loss, a critical security issue, a requirement conflict, or an invalid plan.
187
+
188
+ ## Scope lock
189
+
190
+ Every delegation carries the approved `Plan:` path and `Scope:` globs. The specialist:
191
+
192
+ 1. Reads the plan and executes only the assigned step.
193
+ 2. Touches only files that match `Scope`. If the step needs another file, stop and report.
194
+ 3. Reports out-of-scope findings (a missing permission, a broken test, an unrequested feature)
195
+ without implementing them. The Coordinator decides whether to extend the plan.
196
+ 4. Never expands the scope silently, even when the change looks small or obviously useful.
197
+
198
+ Scope globs must name concrete paths; the Coordinator resolves ambiguity before approval. One
199
+ writer per slice, and parallel writers get disjoint scopes.
200
+
201
+ ## Destructive operations
202
+
203
+ These require the user's explicit authorization, separate from the plan approval. They include
204
+ file deletion (`rm`, `rmdir`, `unlink`, `shred`, `truncate`, `git clean`, `git reset --hard`,
205
+ `git checkout -- .`, destructive `git restore`), database destruction (`DROP`, `TRUNCATE`,
206
+ `DELETE` without `WHERE`, `dropdb`, `dropDatabase`, `FLUSHALL`/`FLUSHDB`, `flyway clean`,
207
+ `prisma migrate reset`, `alembic downgrade base`), and infrastructure/data tools
208
+ (`docker volume rm`, `docker compose down -v`, `kubectl delete`, `terraform destroy`,
209
+ `aws s3 rm`, `gsutil rm`, `mc rm`, `rclone delete`, `rsync --delete`). Any operation the plan
210
+ marks as destructive also qualifies.
211
+
212
+ Mandatory flow:
213
+
214
+ 1. The specialist detects the need and **stops**.
215
+ 2. It reports the operation, why it is needed, its blast radius, and the available backup or
216
+ rollback.
217
+ 3. The Coordinator asks the user for explicit authorization.
218
+ 4. Only then is the operation executed. The runtime still forces the permission prompt for
219
+ known destructive patterns, even when the session is approved and even when an "always"
220
+ approval exists. Shell writes remain a residual risk and the message never prints secrets.
221
+ 5. Without authorization, do not execute; find a safe alternative.
222
+
223
+ Plan approval never authorizes a destructive operation. The runtime pattern list is best effort;
224
+ the specialist's report and the Coordinator's review are the other layer.
225
+
226
+ ## Escalation
227
+
228
+ The Coordinator escalates to the user only for a catastrophic or irreversible operation, data
229
+ loss, critical security, a conflict between requirements, or an invalidated plan. Routine
230
+ implementation decisions, file choices inside the approved scope, test strategy already covered
231
+ by the plan, and retries are the Coordinator's job: decide, record the decision, and continue.
232
+
108
233
  ## Phase 4 — Verify
109
234
 
110
235
  **Owner:** Cybersecurity Engineer and QA Engineer. **Participant:** implementers.
@@ -114,6 +239,8 @@ Verification is continuous, not a final phase:
114
239
  - Security review of each new trust boundary, secret, permission, or data flow.
115
240
  - Tests at the level the risk requires: unit for rules, integration for boundaries, one
116
241
  end-to-end path for the slice.
242
+ - For a feature, the agreed end-to-end path is exercised and every golden and critical dark
243
+ case has evidence or a declared gap.
117
244
  - A real-device or real-environment check before release, not only emulators.
118
245
 
119
246
  **Gate for release:** no open critical/high findings; must-pass checks green; known failures
@@ -121,7 +248,7 @@ documented; residual risk accepted by the user.
121
248
 
122
249
  ## Phase 5 — Release
123
250
 
124
- **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
251
+ **Owner:** SRE Engineer. **Participants:** Coordinator, Cybersecurity.
125
252
 
126
253
  - Version, changelog, signing, and install/upgrade path.
127
254
  - Rollback or roll-forward plan.
@@ -133,7 +260,7 @@ explicitly accepted.
133
260
 
134
261
  ## Phase 6 — Close
135
262
 
136
- **Owner:** Team Lead.
263
+ **Owner:** the Coordinator.
137
264
 
138
265
  - What shipped, with evidence.
139
266
  - What was deferred and why.
@@ -147,6 +274,7 @@ explicitly accepted.
147
274
  | Artifact | When | Maximum before the first commit |
148
275
  |---|---|---|
149
276
  | Operational brief | Frame | 1 page |
277
+ | Feature plan | Feature intake | One visible plan with development and test plan |
150
278
  | Architecture notes / ADRs | When a decision blocks a slice | 1 page per ADR |
151
279
  | Threat model | When a trust boundary or sensitive data appears | The slice's threats only |
152
280
  | Test plan | With the first tests | The first 5 tests |
@@ -171,9 +299,11 @@ first commit, cut it or defer it.
171
299
 
172
300
  | Change | Process |
173
301
  |---|---|
174
- | Typo, docs, one-line fix | Recon → change → check → report |
175
- | Feature in one layer | Scoped conversations and approval → implement → tests → review |
176
- | Cross-layer, data, auth, public contract | Frame → skeleton or thin slice → tests → independent security/QA |
302
+ | Question or read-only investigation | Query: answer directly, no specialists |
303
+ | Typo, docs, one-line fix | Small change: recon → change → check → report |
304
+ | Feature in one layer | Operational brief + approval → implement in scope → tests → review |
305
+ | New capability across layers | Feature intake → visible feature plan → approval → delegated steps → E2E |
306
+ | Cross-layer, data, auth, public contract | Feature plan + independent security/QA, scope lock on every writer |
177
307
  | New project | Frame (1 page) → walking skeleton → slice loop |
178
308
  | Incident | Stabilize → diagnose → fix → regression test → short postmortem |
179
309
 
@@ -190,5 +320,9 @@ request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.
190
320
  - **Demo debt:** a skeleton that only runs in a notebook, not in the repo.
191
321
  - **Phase theater:** marking a phase "done" because its document exists.
192
322
  - **Silent scope growth:** adding a second slice before finishing the first.
323
+ - **Unrequested improvements:** implementing a finding outside `Scope` because it looked useful.
324
+ - **Half-finished feature:** closing with green slices but without the agreed end-to-end path.
325
+ - **Routine interruption:** pausing the approved plan to ask about a decision the plan covers.
326
+ - **Destructive shortcut:** deleting files or data without the user's explicit authorization.
193
327
 
194
328
  If two consecutive work sessions produce no running code, stop and escalate to the user.
@@ -9,6 +9,7 @@ Every change, regardless of type:
9
9
 
10
10
  - [ ] The requested behavior or documentation is complete.
11
11
  - [ ] The diff is scoped; unrelated changes are excluded.
12
+ - [ ] The diff stays inside the approved `Scope`; out-of-scope findings are reported, not implemented.
12
13
  - [ ] The diff has been read end-to-end by the author.
13
14
  - [ ] No secrets, tokens, credentials, or private data are added.
14
15
  - [ ] No debug output, commented-out code, or temporary files remain.
@@ -20,8 +21,21 @@ Every change, regardless of type:
20
21
 
21
22
  ## Gates by change type
22
23
 
24
+ ### Query
25
+
26
+ - [ ] The answer cites the file, command, or behavior it is based on.
27
+ - [ ] No specialist was launched to read or explain code.
28
+ - [ ] No file was modified.
29
+
30
+ ### Small change
31
+
32
+ - [ ] The short operational brief states problem, scope, test, expected evidence, `Aprobado:` and `Scope:`.
33
+ - [ ] One writer owns the change.
34
+ - [ ] The change stays inside the stated scope.
35
+
23
36
  ### Bug fix
24
37
 
38
+ - [ ] The short brief records `Aprobado:` and `Scope:`.
25
39
  - [ ] The failure was reproduced before the fix.
26
40
  - [ ] A test fails without the fix and passes with it (regression test).
27
41
  - [ ] The root cause is addressed, not only the symptom.
@@ -30,16 +44,22 @@ Every change, regardless of type:
30
44
 
31
45
  ### Feature
32
46
 
47
+ - [ ] Feature intake answered before the plan.
48
+ - [ ] The user saw the plan: development steps, agents, parallelism, test plan, evidence, risks, rollback.
49
+ - [ ] The plan has a top-level `Scope:`, Test/Verification/Evidence content, and an affirmative `Aprobado:` with the user's decision, words, and date; observations were iterated.
50
+ - [ ] Every writer received `Plan:` and a disjoint `Scope` equal to or narrower than the plan's scope; a development-table plan had a matching `Step:` and declared agent row; no unrequested change was implemented.
33
51
  - [ ] Acceptance criteria are observable and covered.
34
52
  - [ ] Loading, empty, error, unauthorized, and retry states are handled where relevant.
35
53
  - [ ] Input is validated at the boundary.
36
54
  - [ ] Authorization is enforced server-side, not only in the UI.
37
- - [ ] Tests cover the happy path and the important failure paths.
55
+ - [ ] Tests cover the happy path, the important failure paths, and every critical dark case.
56
+ - [ ] The agreed end-to-end path runs and its evidence is attached.
38
57
  - [ ] Observability exists for new failure modes.
39
58
  - [ ] Documentation is updated.
40
59
 
41
60
  ### Refactor
42
61
 
62
+ - [ ] The short brief records `Aprobado:` and `Scope:`.
43
63
  - [ ] Behavior is unchanged by definition and by tests.
44
64
  - [ ] Baseline tests passed before the refactor.
45
65
  - [ ] Changes are small and reversible; no feature work is mixed in.
@@ -84,6 +104,24 @@ Every change, regardless of type:
84
104
  - [ ] Monitoring and alerts cover the release.
85
105
  - [ ] The release was verified in an environment that resembles production.
86
106
 
107
+ ## Scope and destructive operations
108
+
109
+ A change is not accepted because it is green; it is accepted when it does what was approved
110
+ and nothing else.
111
+
112
+ - **Scope lock:** the writer touched only files matching the delegation's `Scope`, and the
113
+ delegation scope was equal to or narrower than the plan's top-level `Scope`. Any other change
114
+ is reverted or explicitly approved as a plan revision.
115
+ - **Out-of-scope findings:** report them with evidence. Do not implement them, even when they
116
+ look like obvious improvements. The Coordinator decides whether to extend the plan. Read-only
117
+ roles may write their own reports under the planning directory.
118
+ - **Destructive operations:** file deletion, database `DROP`/`TRUNCATE`/`DELETE` without
119
+ `WHERE`, volume or infrastructure destruction, and any operation the plan marks as
120
+ destructive require the user's explicit authorization. Plan approval is not authorization.
121
+ Known patterns force the permission prompt; shell writes remain a residual risk.
122
+ - **Evidence of authorization:** the user's words and the permission decision, recorded in the
123
+ plan or session notes. Never print secrets while requesting it.
124
+
87
125
  ## Delivery gates
88
126
 
89
127
  For a new project or a major change, progress is gated by running code, not by documents:
@@ -91,8 +129,10 @@ For a new project or a major change, progress is gated by running code, not by d
91
129
  | Gate | Evidence |
92
130
  |---|---|
93
131
  | Frame | Operational and technical conversations; user explicitly approves scope, criteria and approach; golden/dark paths identified. |
132
+ | Feature plan | User-visible development plan + test plan + agents/parallelism; top-level `Scope:`; affirmative `Aprobado:`; scopes are disjoint and inside the plan. |
94
133
  | Walking skeleton | The end-to-end path runs with fakes; one command; one test; a commit. |
95
134
  | Slice | Golden and critical dark paths checked; specialist evidence and gaps recorded; scoped diff, demo and commit. |
135
+ | Feature closure | The agreed E2E path runs; every golden and critical dark case has evidence or a declared gap; residual risk reported. |
96
136
  | Release | No open critical/high findings; must-pass checks green; install/upgrade verified in the target. |
97
137
 
98
138
  A planning artifact is not a gate. It is a living note that unblocks a slice. See
@@ -18,6 +18,7 @@ harnesses that support subagents.
18
18
 
19
19
  | Role | Primary question |
20
20
  |---|---|
21
+ | [Coordinator](coordinator.md) | What is the smallest approved slice, who owns it, and what evidence closes it? |
21
22
  | [Team Lead](team-lead.md) | What is the shortest path to a verified delivery? |
22
23
  | [Architect](architect.md) | What boundaries and trade-offs make this correct and evolvable? |
23
24
  | [Cybersecurity Engineer](cybersecurity-engineer.md) | What can be attacked, and what proves the control works? |
@@ -41,7 +42,9 @@ The files remain for v0.1 compatibility but are not installed by `devcomp init`.
41
42
  ## Rules
42
43
 
43
44
  - A role is not a personality. It is a bounded responsibility with explicit outputs.
44
- - The Team Lead routes; specialists do the deep work; QA and Cybersecurity verify.
45
+ - The Coordinator routes; specialists do the deep work; QA and Cybersecurity verify.
46
+ - Every implementation role executes only the delegated step and stays inside the approved
47
+ `Scope`; out-of-scope findings are reported, not implemented.
45
48
  - Every role follows the installed skills and the process. In this repository, the
46
49
  canonical source docs are `core/principles.md`, `core/process.md`, and
47
50
  `core/quality-gates.md`.
@@ -72,3 +72,13 @@ operable under failure.
72
72
  **Verification:** commands and results
73
73
  **Known gaps:** ...
74
74
  ```
75
+
76
+ ## Scope lock
77
+
78
+ Execute only the assigned step from the approved plan and touch only files matching the
79
+ delegation's `Scope`. If the step needs another file, stop and report it. Report out-of-scope
80
+ findings (a broken test, an unrequested feature, a missing permission) with evidence; do not
81
+ implement them, even when they look useful. Destructive operations (file deletion, database
82
+ drop/truncate, volume or infrastructure destruction) require the user's explicit
83
+ authorization, requested through the Coordinator, before execution; stop and report the
84
+ operation, its blast radius and the available rollback.