development-companion 0.0.0-stage → 1.0.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.
Files changed (82) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +229 -2
  3. package/RELEASE.md +107 -0
  4. package/adapters/README.md +113 -0
  5. package/adapters/claude-code/README.md +81 -0
  6. package/adapters/claude-code/adapter.json +10 -0
  7. package/adapters/cline/adapter.json +9 -0
  8. package/adapters/codex/README.md +80 -0
  9. package/adapters/codex/adapter.json +9 -0
  10. package/adapters/copilot-cli/adapter.json +9 -0
  11. package/adapters/cursor/adapter.json +9 -0
  12. package/adapters/gemini-cli/adapter.json +9 -0
  13. package/adapters/generic/adapter.json +9 -0
  14. package/adapters/opencode/README.md +89 -0
  15. package/adapters/opencode/adapter.json +9 -0
  16. package/adapters/pi/README.md +83 -0
  17. package/adapters/pi/adapter.json +9 -0
  18. package/adapters/windsurf/adapter.json +9 -0
  19. package/bin/devcomp.mjs +8 -0
  20. package/core/guidelines/backend.md +103 -0
  21. package/core/guidelines/collaboration.md +78 -0
  22. package/core/guidelines/frontend.md +106 -0
  23. package/core/guidelines/security.md +90 -0
  24. package/core/guidelines/testing.md +90 -0
  25. package/core/principles.md +208 -0
  26. package/core/process.md +224 -0
  27. package/core/quality-gates.md +192 -0
  28. package/core/roles/README.md +55 -0
  29. package/core/roles/architect.md +75 -0
  30. package/core/roles/backend-engineer.md +74 -0
  31. package/core/roles/cybersecurity-engineer.md +55 -0
  32. package/core/roles/desktop-linux-engineer.md +50 -0
  33. package/core/roles/desktop-macos-engineer.md +50 -0
  34. package/core/roles/desktop-windows-engineer.md +50 -0
  35. package/core/roles/frontend-engineer.md +72 -0
  36. package/core/roles/mobile-engineer.md +50 -0
  37. package/core/roles/multiplatform-engineer.md +49 -0
  38. package/core/roles/orchestrator.md +69 -0
  39. package/core/roles/qa-engineer.md +69 -0
  40. package/core/roles/reviewer.md +77 -0
  41. package/core/roles/sre-engineer.md +51 -0
  42. package/core/roles/team-lead.md +67 -0
  43. package/core/workflow.md +169 -0
  44. package/package.json +53 -4
  45. package/skills/architecture-design/SKILL.md +116 -0
  46. package/skills/backend-development/SKILL.md +127 -0
  47. package/skills/code-review/SKILL.md +144 -0
  48. package/skills/delivery-orchestration/SKILL.md +119 -0
  49. package/skills/deployment-sre/SKILL.md +111 -0
  50. package/skills/desktop-development/SKILL.md +51 -0
  51. package/skills/development-workflow/SKILL.md +158 -0
  52. package/skills/frontend-development/SKILL.md +136 -0
  53. package/skills/linux-development/SKILL.md +44 -0
  54. package/skills/macos-development/SKILL.md +45 -0
  55. package/skills/mobile-development/SKILL.md +60 -0
  56. package/skills/multiplatform-development/SKILL.md +45 -0
  57. package/skills/project-discovery/SKILL.md +122 -0
  58. package/skills/security-review/SKILL.md +109 -0
  59. package/skills/test-strategy/SKILL.md +109 -0
  60. package/skills/ux-design/SKILL.md +108 -0
  61. package/skills/windows-development/SKILL.md +45 -0
  62. package/src/args.mjs +42 -0
  63. package/src/cli.mjs +449 -0
  64. package/src/content.mjs +72 -0
  65. package/src/detect.mjs +119 -0
  66. package/src/install.mjs +186 -0
  67. package/src/prompt.mjs +35 -0
  68. package/src/rules.mjs +83 -0
  69. package/src/scaffold.mjs +433 -0
  70. package/templates/artifacts/01-operational-brief.md +37 -0
  71. package/templates/artifacts/02-architecture.md +33 -0
  72. package/templates/artifacts/03-threat-model.md +29 -0
  73. package/templates/artifacts/04-test-plan.md +35 -0
  74. package/templates/artifacts/05-ux-spec.md +31 -0
  75. package/templates/artifacts/06-delivery-plan.md +29 -0
  76. package/templates/artifacts/07-security-report.md +25 -0
  77. package/templates/artifacts/08-qa-report.md +32 -0
  78. package/templates/artifacts/09-runbook.md +43 -0
  79. package/templates/artifacts/10-closure.md +25 -0
  80. package/templates/artifacts/README.md +17 -0
  81. package/templates/rules/AGENTS.block.md +36 -0
  82. package/templates/rules/CLAUDE.block.md +3 -0
@@ -0,0 +1,90 @@
1
+ # Testing Guidelines
2
+
3
+ Tests exist to prove behavior and prevent regressions. They are evidence, not a
4
+ ritual and not a coverage target.
5
+
6
+ ## Strategy
7
+
8
+ Use the cheapest test level that can prove the behavior:
9
+
10
+ | Level | Use for | Avoid |
11
+ |---|---|---|
12
+ | **Unit** | Pure logic, invariants, edge cases, parsing, calculations | Testing framework wiring or private methods |
13
+ | **Component** | UI behavior, states, keyboard interaction | Snapshot-only assertions |
14
+ | **Integration** | Real database, API contract, module boundaries | Mocking the thing under test |
15
+ | **End-to-end** | Critical user flows, auth, payments, cross-service behavior | Covering every permutation |
16
+ | **Manual** | Visual quality, accessibility, exploratory checks | Replacing automatable regression tests |
17
+
18
+ The shape should follow risk, not a fixed pyramid. A small project may need mostly
19
+ integration tests; a complex domain needs strong unit coverage.
20
+
21
+ ## What to test
22
+
23
+ - The acceptance criteria, in observable terms.
24
+ - Boundaries: empty, null, minimum, maximum, malformed, oversized, duplicate.
25
+ - Failure paths: invalid input, denied access, timeout, conflict, partial failure.
26
+ - State transitions: double submit, retry, refresh, stale cache, rollback.
27
+ - Contracts: request/response shape, status codes, error codes, events.
28
+ - Regressions: every fixed bug gets a test that fails without the fix.
29
+ - Accessibility: keyboard operation and accessible names for key flows.
30
+ - Performance: only where a budget or regression risk is real.
31
+
32
+ ## What not to test
33
+
34
+ - Private implementation details that are free to change.
35
+ - Framework behavior you did not write.
36
+ - Exact log strings or CSS classes unless they are part of the contract.
37
+ - Mocks asserting that a mock was called, with no observable outcome.
38
+ - Every permutation of a combinatorial space; choose representative cases.
39
+
40
+ ## Bug fixes
41
+
42
+ 1. Reproduce the bug with a failing test.
43
+ 2. Confirm the test fails for the right reason.
44
+ 3. Fix the root cause.
45
+ 4. Confirm the test passes and the rest of the suite still passes.
46
+ 5. Add adjacent cases if the same defect could exist elsewhere.
47
+
48
+ If a failing test is impossible, document the manual reproduction and why automation
49
+ is not feasible.
50
+
51
+ ## Determinism
52
+
53
+ - Control time, randomness, network, and external services.
54
+ - Isolate test data; do not depend on execution order or shared mutable state.
55
+ - Avoid sleeps. Wait for a condition or use fake timers.
56
+ - Make retries explicit and bounded; do not hide flakiness.
57
+ - Treat a flaky test as a defect, not as noise.
58
+
59
+ ## Test data
60
+
61
+ - Use builders or factories with sensible defaults and explicit overrides.
62
+ - Keep fixtures small and readable; a test should show the relevant data inline.
63
+ - Never use production personal data.
64
+ - Use realistic values for formats, time zones, encodings, and money.
65
+
66
+ ## Coverage
67
+
68
+ - Coverage is a signal for untested areas, not a goal by itself.
69
+ - Do not chase 100%; cover risk and contracts.
70
+ - A high-coverage suite that asserts nothing useful is worse than a small, meaningful
71
+ suite.
72
+ - Review uncovered branches in critical code.
73
+
74
+ ## CI and local checks
75
+
76
+ - Run the fastest checks first: typecheck, lint, unit.
77
+ - Run integration/e2e where the environment supports them.
78
+ - Fail the build on test failures, not on warnings you have decided to ignore.
79
+ - Keep a documented command to run the full suite locally.
80
+ - Report skipped checks explicitly.
81
+
82
+ ## Anti-patterns
83
+
84
+ - Testing the mock instead of the behavior.
85
+ - Snapshot tests for dynamic UI with no semantic assertions.
86
+ - One giant end-to-end test that duplicates unit coverage.
87
+ - Sleep-based synchronization.
88
+ - Shared database state between tests.
89
+ - Asserting implementation details that make refactors painful.
90
+ - Adding a test after the fact that would pass even with the bug.
@@ -0,0 +1,208 @@
1
+ # Engineering Principles
2
+
3
+ These principles are the non-negotiable base for every role, skill, and adapter.
4
+ They are deliberately harness-neutral: they apply whether the work is done by
5
+ OpenCode, Claude Code, Codex, Pi, or a human.
6
+
7
+ ## The prime directive
8
+
9
+ **Leave the system working and verifiably better than you found it.**
10
+
11
+ "Better" means the requested problem is solved, the change is understandable,
12
+ and the evidence shows it works. Clever code that cannot be verified is not better.
13
+
14
+ ---
15
+
16
+ ## 1. Understand before changing
17
+
18
+ Read the relevant code, trace the real execution path, and check existing
19
+ conventions before proposing a change. A plausible guess is not understanding.
20
+
21
+ **In practice:** find the entry point, the data flow, the tests, and the closest
22
+ existing example. State assumptions explicitly when you cannot confirm them.
23
+
24
+ **Red flags:** editing from filenames alone; inventing APIs; ignoring local
25
+ patterns; "it probably works".
26
+
27
+ ## 2. Solve the problem, not the symptom
28
+
29
+ Fix the cause, not the error message. A workaround is acceptable only when it is
30
+ explicit, bounded, and documented as debt.
31
+
32
+ **In practice:** reproduce the failure, identify the failing invariant, and add a
33
+ regression test that would have caught it.
34
+
35
+ **Red flags:** swallowing exceptions; adding sleeps; disabling checks; special-casing
36
+ test data.
37
+
38
+ ## 3. Make the smallest coherent change
39
+
40
+ Prefer the smallest diff that fully solves the problem. Small changes are easier to
41
+ review, test, revert, and reason about.
42
+
43
+ **In practice:** keep unrelated refactors out. If a larger change is genuinely
44
+ required, explain why and split it into reviewable steps.
45
+
46
+ **Red flags:** drive-by renames; mass formatting; "while I was here" changes;
47
+ rewriting a module to fix a one-line bug.
48
+
49
+ ## 4. Contracts are promises
50
+
51
+ APIs, component props, database schemas, events, file formats, and public types are
52
+ contracts. Changing them affects callers you may not see.
53
+
54
+ **In practice:** search all call sites, update consumers, preserve backward
55
+ compatibility where required, and document breaking changes.
56
+
57
+ **Red flags:** changing a response shape without checking clients; nullable fields
58
+ becoming required; silent semantic changes.
59
+
60
+ ## 5. Validate at the boundary; trust nothing
61
+
62
+ All external input is untrusted: HTTP requests, user input, files, environment
63
+ variables, third-party APIs, and model output.
64
+
65
+ **In practice:** validate shape, type, range, size, and encoding at the edge.
66
+ Reject unknown or malformed input with a clear error. Keep validation close to the
67
+ boundary, not scattered through the domain.
68
+
69
+ **Red flags:** trusting client-side checks; parsing without limits; passing raw
70
+ input into queries, templates, shells, or file paths.
71
+
72
+ ## 6. Make invalid states unrepresentable
73
+
74
+ Prefer types, schemas, and invariants that prevent bad states instead of relying on
75
+ comments or vigilance.
76
+
77
+ **In practice:** use discriminated unions, enums, branded types, database
78
+ constraints, and constructors that enforce invariants. Validate once, then work with
79
+ a trusted type.
80
+
81
+ **Red flags:** boolean soup; optional fields that must always be present together;
82
+ "remember to check X" comments.
83
+
84
+ ## 7. Security and privacy are defaults
85
+
86
+ Every feature has a threat model, even a small one. Authentication, authorization,
87
+ data exposure, injection, and secrets are part of the design, not a final checklist.
88
+
89
+ **In practice:** deny by default; authorize per resource; minimize collected data;
90
+ keep secrets server-side; encode output; log without PII. See
91
+ `core/guidelines/security.md`.
92
+
93
+ **Red flags:** "we'll add auth later"; secrets in client code or logs; authorization
94
+ checks only in the UI; unbounded file uploads.
95
+
96
+ ## 8. Accessibility and performance are functional requirements
97
+
98
+ A fast, accessible interface is part of correctness. An inaccessible feature is a
99
+ broken feature for real users.
100
+
101
+ **In practice:** semantic HTML, keyboard access, visible focus, labels, contrast,
102
+ reduced motion, responsive layouts, and loading/error/empty states. Measure
103
+ performance against a budget instead of guessing.
104
+
105
+ **Red flags:** div buttons; placeholder-only labels; horizontal scroll on mobile;
106
+ unbounded lists; layouts that shift after load.
107
+
108
+ ## 9. Tests are evidence, not decoration
109
+
110
+ Tests exist to prove behavior and prevent regressions. A test that never fails is
111
+ not evidence.
112
+
113
+ **In practice:** test behavior and contracts, not private implementation details.
114
+ For a bug fix, write a failing test first. For a refactor, prove behavior is
115
+ unchanged.
116
+
117
+ **Red flags:** snapshot-only coverage; tests that assert the mock; skipped tests
118
+ without a reason; coverage as the only goal.
119
+
120
+ ## 10. Reversible by design
121
+
122
+ Prefer changes that can be rolled back or migrated safely. Irreversible operations
123
+ need explicit approval and a recovery plan.
124
+
125
+ **In practice:** use expand/contract migrations, feature flags for risky behavior,
126
+ idempotent jobs, and backups before destructive operations.
127
+
128
+ **Red flags:** dropping columns in the same release that stops using them; no
129
+ rollback path; one-way data transformations.
130
+
131
+ ## 11. Observe what you ship
132
+
133
+ If it can fail in production, you need to know. Logs, metrics, and traces are part
134
+ of the feature, not an operations afterthought.
135
+
136
+ **In practice:** structured logs with correlation IDs, meaningful error messages,
137
+ health checks, and metrics for the failure modes that matter. Never log secrets or
138
+ PII.
139
+
140
+ **Red flags:** silent failures; generic "something went wrong"; no way to trace a
141
+ request; logging entire payloads.
142
+
143
+ ## 12. Communicate uncertainty and decisions
144
+
145
+ State what you know, what you assume, and what you could not verify. Hidden
146
+ uncertainty becomes someone else's incident.
147
+
148
+ **In practice:** report evidence, open questions, and residual risk. Record
149
+ architectural decisions with context and consequences. Ask before making a
150
+ high-impact choice on the user's behalf.
151
+
152
+ **Red flags:** confident claims without checks; silent scope changes; decisions
153
+ buried in chat instead of documented.
154
+
155
+ ## 13. Evidence over claims
156
+
157
+ A change is not done because it is described as done. It is done when a check, test,
158
+ request, screenshot, CVE, or metric proves it.
159
+
160
+ **In practice:** report the command and its result; attach the failing request or the
161
+ screenshot; state what could not be verified.
162
+
163
+ **Red flags:** "should work"; "tests pass" without output; a finding without reproduction;
164
+ a completion report that summarizes intention instead of evidence.
165
+
166
+ ## 14. Environment variables: names, not values
167
+
168
+ Agents may need to know whether a variable is configured. They never need its value.
169
+
170
+ **In practice:** read key names from `.env.example`; check presence with
171
+ `test -n "$VAR"` and print only set/unset; redact logs. The CLI never opens `.env`.
172
+
173
+ **Red flags:** `cat .env`; `env`; `printenv` without a name; tokens in logs, screenshots,
174
+ or reports.
175
+
176
+ ## 15. The domain is independent; patterns need a reason
177
+
178
+ Business rules must survive a change of framework, database, vendor, or delivery
179
+ mechanism. Architecture exists to protect that independence.
180
+
181
+ **In practice:** keep `domain` free of framework and infrastructure imports; define ports
182
+ owned by the inside; implement adapters outside; record non-obvious patterns in an ADR.
183
+
184
+ **Red flags:** ORM entities as domain models; HTTP types in use cases; a pattern applied
185
+ "because it is best practice" with no problem to solve.
186
+
187
+ ## 16. Design documents are local by default; memory is optional
188
+
189
+ The repository should stay focused on code. Design decisions, evidence, and reports belong
190
+ in `.companion/local/`, which is ignored by git; tracking them is an explicit opt-in.
191
+ Engram can index them, but the files remain the source of truth.
192
+
193
+ **In practice:** write discovery, architecture, test plans, and reports locally; use
194
+ `--track-docs` when the team wants them versioned; save durable decisions to memory when
195
+ available.
196
+
197
+ **Red flags:** committing local design notes by accident; treating a memory entry as the
198
+ only record; losing a decision because it lived only in chat.
199
+
200
+ ---
201
+
202
+ ## How to use these principles
203
+
204
+ - When principles conflict, prioritize **correctness and safety** over speed, and
205
+ **reversibility** over elegance.
206
+ - When a principle cannot be followed, say so explicitly and explain the trade-off.
207
+ - When adding a new rule, ask: does it change behavior, or only restate these
208
+ principles? If it only restates them, do not add it.
@@ -0,0 +1,224 @@
1
+ # Development Process
2
+
3
+ This is the default process for a new project or a major change. It scales down for small
4
+ changes; see `core/workflow.md`.
5
+
6
+ The process is owned by the **Team Lead**. Each phase has an artifact in
7
+ `.companion/local/` and a gate that requires evidence.
8
+
9
+ ```text
10
+ 0 Bootstrap
11
+ → 1 Operational discovery
12
+ → 2 Architecture + security (in parallel)
13
+ → 3 Test strategy
14
+ → 4 UX/UI
15
+ → 5 Delivery plan
16
+ → 6 Implementation
17
+ → 7 Security verification
18
+ → 8 QA verification
19
+ → 9 Deployment
20
+ → 10 Closure
21
+ ```
22
+
23
+ ## Phase 0 — Bootstrap
24
+
25
+ **Owner:** CLI.
26
+
27
+ - Detect the repository, harness, package manager, profile, and branch convention.
28
+ - Install `AGENTS.md` and `CLAUDE.md` using keep, append, or replace.
29
+ - Install process skills, roles, and native bindings.
30
+ - Write `.companion/config.json` and ignore `.companion/local/`.
31
+
32
+ **Gate:** `devcomp doctor` passes; existing rules were not lost.
33
+
34
+ ## Phase 1 — Operational discovery
35
+
36
+ **Owner:** Team Lead. **Participant:** the user.
37
+
38
+ Ask, one topic at a time:
39
+
40
+ - What problem, for whom, and why now?
41
+ - What does success look like, and how is it measured?
42
+ - What is in scope and out of scope for the first release?
43
+ - Are there existing repositories, prototypes, designs, or documents?
44
+ - Where will it run: on-prem, VPS, Dokploy, Coolify, cloud?
45
+ - Which third-party services, APIs, MCPs, or on-device capabilities are required?
46
+ - What data is stored, where, and for how long?
47
+ - What authentication is needed: local, OIDC, Firebase, other?
48
+ - Which platforms are targets?
49
+ - What are the deadline, team, budget, and maintenance constraints?
50
+ - Which branch convention is used: gitflow, GitLab flow, trunk-based, GitHub flow, custom?
51
+ Detect it, then ask the user to confirm.
52
+ - What does "done" mean?
53
+
54
+ **Artifact:** `.companion/local/01-operational-brief.md`.
55
+
56
+ **Gate:** the user confirms the brief; no blocking operational question remains.
57
+
58
+ ## Phase 2 — Architecture and security
59
+
60
+ **Owner:** Architect. **Participant:** Cybersecurity Engineer, in parallel.
61
+
62
+ Technical questions:
63
+
64
+ - Stack and versions: verify the latest stable release.
65
+ - Monorepo or single repo? Which workspace tool?
66
+ - Monolith, modular monolith, or microservices? Why?
67
+ - Layered, hexagonal, or tactical DDD?
68
+ - Data stores, schema, migrations.
69
+ - AuthN/AuthZ, tenancy, secrets.
70
+ - Integrations, queues, events, webhooks, idempotency.
71
+ - Deployment, observability, backups, rollback.
72
+ - Performance budget and expected load.
73
+
74
+ Security, in parallel:
75
+
76
+ - Assets, actors, entry points, trust boundaries.
77
+ - Threat model and top risks.
78
+ - Controls and accepted risks.
79
+ - Relevant CVEs and supply-chain concerns.
80
+
81
+ **Artifacts:** `.companion/local/02-architecture.md`,
82
+ `.companion/local/03-threat-model.md`, and `adr/NNN-*.md`.
83
+
84
+ **Gate:** stack and versions approved; boundaries and patterns recorded; threats have a
85
+ control or an explicit acceptance; no architecture blocker remains.
86
+
87
+ ## Phase 3 — Test strategy
88
+
89
+ **Owner:** QA Engineer. **Participants:** Team Lead, Architect.
90
+
91
+ - Golden paths, dark paths, and edge cases.
92
+ - Test levels and tools.
93
+ - Data, fixtures, and environments.
94
+ - Load/stress scenario, budgets, and target environment.
95
+ - Accessibility, visual, and cross-platform checks.
96
+ - Security checks.
97
+ - Evidence format and exit criteria.
98
+
99
+ **Artifact:** `.companion/local/04-test-plan.md`.
100
+
101
+ **Gate:** every acceptance criterion maps to a test; critical failure paths are covered
102
+ or explicitly accepted.
103
+
104
+ ## Phase 4 — UX/UI
105
+
106
+ **Owner:** Frontend Engineer. **Participants:** the user, QA.
107
+
108
+ - Flows and information architecture.
109
+ - Wireframes or mockups in `.companion/local/mockups/`.
110
+ - States: loading, empty, error, unauthorized, offline, retry, success.
111
+ - Responsive breakpoints and behavior.
112
+ - Accessibility: keyboard, focus, labels, contrast, reduced motion.
113
+ - Motion with purpose.
114
+ - Design tokens and components.
115
+ - Screenshots at desktop and mobile widths.
116
+
117
+ **Artifact:** `.companion/local/05-ux-spec.md` plus mockups and screenshots.
118
+
119
+ **Gate:** the user approves the design; states and accessibility are covered.
120
+
121
+ ## Phase 5 — Delivery plan
122
+
123
+ **Owner:** Team Lead. **Participants:** all specialists.
124
+
125
+ - Deliverables with owners.
126
+ - Dependencies and critical path.
127
+ - Parallel vs serial work.
128
+ - Branch and release flow.
129
+ - Gates and evidence.
130
+ - Risks and mitigations.
131
+
132
+ **Artifact:** `.companion/local/06-delivery-plan.md`.
133
+
134
+ **Gate:** every task has an owner, an output, and a verification; no two writers own the
135
+ same files.
136
+
137
+ ## Phase 6 — Implementation
138
+
139
+ **Owner:** specialists. **Coordinator:** Team Lead.
140
+
141
+ - Contracts and schemas first.
142
+ - Tests alongside behavior; TDD if the project chose it.
143
+ - Small, reversible changes.
144
+ - Domain independent from infrastructure.
145
+ - No secrets, debug output, or dead code.
146
+ - Update ADRs when reality contradicts the plan.
147
+ - Self-review before requesting verification.
148
+
149
+ **Gate:** local checks pass; the diff is scoped; tests cover the new behavior.
150
+
151
+ ## Phase 7 — Security verification
152
+
153
+ **Owner:** Cybersecurity Engineer. **Participant:** implementers.
154
+
155
+ - Update the threat model.
156
+ - OWASP ASVS as a reference, not a checklist ritual.
157
+ - SAST, dependency audit, secret scanning, container/configuration scanning.
158
+ - Test authn, authz, sessions, uploads, payments, webhooks, rate limits.
159
+ - Report every finding with reproducible evidence.
160
+ - Re-test fixes.
161
+
162
+ **Artifact:** `.companion/local/07-security-report.md`.
163
+
164
+ **Gate:** no open critical or high findings; medium risks have an owner and a date.
165
+
166
+ ## Phase 8 — QA verification
167
+
168
+ **Owner:** QA Engineer. **Participant:** implementers.
169
+
170
+ - Functional and regression tests.
171
+ - Golden/dark paths and edge cases.
172
+ - Load/stress evidence in a target-like environment.
173
+ - Accessibility and visual review against the mockup.
174
+ - Cross-platform and responsive checks.
175
+ - Every failure with reproduction and evidence; fixes are re-verified.
176
+
177
+ **Artifact:** `.companion/local/08-qa-report.md`.
178
+
179
+ **Gate:** must-pass checks are green; known failures are documented; performance is within
180
+ budget or explicitly accepted.
181
+
182
+ ## Phase 9 — Deployment
183
+
184
+ **Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
185
+
186
+ - Docker/compose baseline; VPS with Dokploy or Coolify; cloud reference provider.
187
+ - Secrets in the target manager; never in the repository.
188
+ - Migrations with a tested rollback.
189
+ - Healthchecks, logs, metrics, traces, alerts.
190
+ - Smoke tests against the real target.
191
+ - Performance evidence in the target environment.
192
+
193
+ **Artifact:** `.companion/local/09-runbook.md`.
194
+
195
+ **Gate:** smoke tests pass; rollback is tested; secrets are outside the repo; monitoring is
196
+ active.
197
+
198
+ ## Phase 10 — Closure
199
+
200
+ **Owner:** Team Lead. **Participants:** all.
201
+
202
+ - What was delivered and why.
203
+ - Evidence per gate.
204
+ - Residual risks and accepted debt.
205
+ - Runbook and handoff.
206
+ - Next steps.
207
+
208
+ **Artifact:** `.companion/local/10-closure.md`.
209
+
210
+ **Gate:** the user accepts; no claim of "done" lacks evidence; the repository is consistent.
211
+
212
+ ## Scaling down
213
+
214
+ | Change | Process |
215
+ |---|---|
216
+ | Typo, docs, one-line fix | Recon → change → check → report |
217
+ | Feature in one layer | Brief → plan → implement → tests → self-review |
218
+ | Cross-layer, data, auth, public contract | Full process + independent security and QA |
219
+ | Incident | Stabilize → diagnose → fix → regression test → short postmortem |
220
+
221
+ ## Evidence
222
+
223
+ A gate is not closed by a narrative. It is closed by a command and its output, a test, a
224
+ request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.