Repository navigation
Expand file tree
/
Copy pathAUTOSDE.yaml
More file actions
1520 lines (1416 loc) · 87.1 KB
/
Copy pathAUTOSDE.yaml
File metadata and controls
1520 lines (1416 loc) · 87.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Kiro Crew AutoSDE Rules
#
# Root rules cover backend Python plus cross-stack invariants whose file patterns
# span backend, frontend, and docs. Frontend-only rules live in
# website/AUTOSDE.yaml. Both files are enforced by the Claude and Codex PR
# reviewers.
#
# De-Amazoned from the internal package rule set (internal links removed).
# Blocking rules are backed by real vulnerabilities/incidents in this codebase.
custom-rules:
- id: feature-map-correctness
blocking: true
file-patterns:
- "docs/feature-map/README.md"
- "website/src/pages/**"
- "src/kiro_crew/dashboard/handlers/**"
- "src/kiro_crew/dashboard/chat_api/**"
- "src/kiro_crew/dashboard/messaging_api/**"
- "src/kiro_crew/dashboard/file_api/**"
- "src/kiro_crew/dashboard/agent_admin/**"
- "src/kiro_crew/dashboard/routes/**"
- "src/kiro_crew/dashboard/server.py"
- "src/kiro_crew/dashboard/server_*.py"
- "src/kiro_crew/dashboard/server_runtime/**/*.py"
- "website/src/App.tsx"
rule: |
Keep the feature map semantically aligned with every structural dashboard
change in the pull request. The mechanical gate proves only that the map
was touched; this rule judges whether that edit is true.
- For every dashboard page or backend handler added or deleted in the
diff, and every `<Route>` registration added or removed in
`website/src/App.tsx`, require the corresponding map row to be added,
removed, or updated. A new feature needs a new or updated row; a removed
feature needs its row removed or updated.
- Verify every changed map row against the code in the diff. Its user
navigation path, frontend page, backend handler, and representative
endpoints must exist and identify the feature's real ownership.
- Reject unrelated map churn. A whitespace-only, reflow-only, or cosmetic
map edit beside a real structural change is a token touch made only to
satisfy `scripts/check_feature_map.py`, not evidence the map was reviewed.
- The map's net additions, removals, and row edits must match the scope the
pull request claims. Do not accept rows for unrelated features or omit
a structural feature because the map file changed somewhere else.
- id: backend-security-controls
blocking: true
file-patterns:
- "src/kiro_crew/**/*.py"
rule: |
Enforce KiroCrew backend security controls, based on real vulnerabilities
found and fixed in this codebase.
- Never read sensitive credential paths (for example ~/.aws, ~/.ssh,
~/.gnupg, ~/.docker, ~/.kube, ~/.npmrc, ~/.pypirc, ~/.netrc,
~/.git-credentials, ~/.kiro/crew/.env and the pre-move ~/.kirocrew/.env;
the canonical list is `_SENSITIVE_HOME_DIRS` in security/paths_lists.py, and
this list is illustrative, not the enforcement scope). File reads of
user- or LLM-influenced paths MUST go
through hooks.py, which enforces is_sensitive_path()
(security/paths.py); trusted
fixed-path internal config/package reads are exempt. Never weaken that
keystone.
- Never trust LLM output. Scan with redact_exfiltration_urls() AND
redact_credentials() before posting to Slack, the dashboard, or any
external surface. redact_credentials() catches raw credential patterns
(AKIA*, SecretAccessKey=, private-key headers) and base64 variants.
- Validate all MCP tool inputs via validation.py schemas. Never pass raw
LLM input to the filesystem, a subprocess, or a database.
- Authorization must be deny-by-default: reject unless positively
confirmed. Never write `if x and y and z` guards where a falsy value
silently skips the check (the fail-open bug class this rule guards).
- All agent subprocesses must go through AcpClient._spawn() (or the
provider spawn helpers), which apply an OS-level sandbox via wrap_argv().
- The dashboard binds to 127.0.0.1 by default (local-only). Binding to
0.0.0.0 is permitted ONLY when token-auth middleware is active. Never
bind to 0.0.0.0 without token auth — see dashboard/urls.py:is_local_only()
(re-exported by dashboard/origin.py) and
dashboard/token_auth.py:token_auth_middleware().
- All tool invocations and permission decisions MUST emit a SEL audit
event via sel.py.
- Never hardcode secrets. Store them in ~/.kiro/crew/.env with chmod 600,
enforced at load time (log a warning if the chmod fails).
- Auto-approve / YOLO mode: an AD-HOC activation (Slack command, dashboard
picker, API) MUST auto-expire — either on a timed TTL capped at the
SafetyOverride 24h ceiling, or, when the operator selects the
`until_shutdown` duration, when the process stops. Never persist an
ad-hoc grant across a restart. A grant the operator DECLARED in
owner-only config (`agent.dangerously_skip_permissions`; the camelCase and legacy `yolo` spellings are also read) MAY
persist without expiry and IS re-established at each startup: it is a
standing instruction, is held in memory only (never written to disk), is
cleared when another approval mode is selected, and MUST remain deniable
by the enterprise governance ceiling (the `yolo_duration` scope's
`permanent` and `until_shutdown` members, evaluated fail-closed against
the HOST profile). There is deliberately NO dashboard toggle for the
declared grant. Every activation still routes through the SafetyOverride
singleton (safety_override.py) and emits a SEL event. Never set the mode
globals directly.
- Mermaid securityLevel must be 'strict' (iframe sandbox), never 'loose'
(which allows JS execution from diagram payloads).
- id: no-blocking-call-on-event-loop
blocking: true
file-patterns:
- "src/kiro_crew/**/*.py"
rule: |
Do NOT add a blocking syscall that runs on the asyncio event loop. The
gateway runs everything on one loop; a single blocking call there freezes
every task — the user's chat turn AND the liveness heartbeat — until the
watchdog kills the process and the supervisor respawns into the same
condition (a crash loop). This has caused multiple production wedges.
Calls that block in the kernel and MUST NOT run on the loop:
- subprocess.run / call / check_output / check_call / Popen(...).communicate()
- os.close() on a file descriptor (PTY master, socket) — can block on a
wedged peer
- os.waitpid / os.system / os.popen
- time.sleep (use `await asyncio.sleep`)
- synchronous network or DNS (requests.*, blocking socket.*, getaddrinfo)
- large synchronous file IO or filesystem walks
If such a call is reachable from the event loop (in an `async def`, or in
a sync helper called transitively from an async handler, a periodic task,
or a cron tick), offload it:
await asyncio.get_running_loop().run_in_executor(
subprocess_executor(), blocking_fn, *args)
or rewrite it with an async API (asyncio.create_subprocess_exec,
asyncio.sleep, aiohttp).
Allowed (do NOT flag):
- the call is already inside run_in_executor(...) or handed to a thread
- one-shot CLI / setup / packaging paths that run before the loop starts
- test code
When in doubt, offload — a leaked worker thread is survivable; a frozen
loop is not.
- id: no-new-work-on-gateway-boot-path
blocking: true
file-patterns:
- "src/kiro_crew/slack/gateway.py"
- "src/kiro_crew/slack/gateway_runtime/**/*.py"
- "src/kiro_crew/dashboard/server.py"
- "src/kiro_crew/dashboard/server_*.py"
- "src/kiro_crew/dashboard/server_runtime/**/*.py"
- "src/kiro_crew/dashboard/handlers/**/*.py"
- "src/kiro_crew/dashboard/messaging_api/**/*.py"
- "src/kiro_crew/dashboard/file_api/**/*.py"
- "src/kiro_crew/dashboard/agent_admin/**/*.py"
- "src/kiro_crew/cli.py"
- "src/kiro_crew/cli_gateway_boot.py"
- "src/kiro_crew/cli_jail.py"
- "src/kiro_crew/cli_knowledge.py"
- "src/kiro_crew/cli_logging.py"
- "src/kiro_crew/cli_parser_*.py"
- "src/kiro_crew/cli_server.py"
- "src/kiro_crew/cli_server_*.py"
- "src/kiro_crew/dashboard/routes/**/*.py"
- "src/kiro_crew/deploy/handlers.py"
rule: |
Do NOT add work to the gateway boot path. Everything between process
start and the moment the dashboard socket accepts requests runs once, in
order, on one thread — so every statement added there is paid by every
user on every launch, and it delays the point at which the app is usable.
A slow boot also compounds: the longer startup holds the event loop, the
more likely the loop-stall watchdog kills the process and the supervisor
respawns into the same startup, turning a latency bug into a crash loop.
The boot path means, specifically:
- `GatewayOrchestrator.run()` up to the `KIROCREW_READY` print
- `start_dashboard()` (the gateway's default dashboard) up to
`await site.start()` on the reserved `SockSite`
- `start_api_server()` (the `--no-dashboard` API-only path) up to
`await _start_site(site, port)`
- any `_init_*()`, `setup_*_routes()`, `register()` / `register_all()` /
`register_routes()` route registrar reached from those
- `cli.py`'s gateway command before `asyncio.run()`, and
`cli_server._gateway()` up to `run_gateway()`
Reject a diff that puts any of these on that path:
1. A new awaited or synchronous step before the socket binds. Adding one
is a product decision about startup latency, not a detail.
2. Subsystem construction as a side effect of route registration. A
`setup_*_routes()` / `register(app)` / `register_routes()` registrar
must only register routes
(`app.router.add_*`). Building a pipeline, opening a store, or
constructing a client there drags that subsystem's whole init onto the
boot path, where nobody looking at the route file will find it.
3. Work whose cost scales with user data — row counts, corpus size,
file counts, session history. This is forbidden on the boot path at
any measured speed, because the measurement was taken on an empty
profile and the growth is unbounded.
4. Unconditional maintenance: orphan sweeps, integrity scans, vacuum,
reindex, or a migration that scans rather than checks a version. Boot
is not a maintenance window. Work that finds nothing on a healthy
install still costs every user every launch.
5. Eager import or instantiation of a subsystem that is optional,
disabled, or feature-flagged off. Gate the import, not just the
handler — an import the enabled-check happens after is not gated.
6. Touching a lazily-initialized accessor from boot code. A `@property`
documented as lazy-init is a contract; reading it at startup breaks
that contract silently and moves the cost to a place its author did
not intend.
Instead, defer it:
- a first-use accessor that constructs once and memoizes on the app
- `asyncio.create_task(...)` for work that may finish after readiness
- `await asyncio.to_thread(...)` when init genuinely must happen at boot
and genuinely blocks, so it does not hold the loop
- let dependent routes return 503 until the subsystem is ready, rather
than making every launch wait for a subsystem most launches never use
Allowed: route registration itself, in-memory wiring, O(1) config reads,
and bounded fail-closed safety checks that must precede serving traffic
(those still belong off the loop).
If a step genuinely must run at boot, the PR must say why it cannot be
deferred and state its worst-case bound on a large profile — not on the
author's machine.
- id: no-test-side-effects
blocking: true
file-patterns:
- "test/**/*.py"
- "tests/**/*.py"
- "packages/**/tests/**/*.py"
- "src/kiro_crew/apps/builtins/**/tests/**/*.py"
- "src/kiro_crew/apps/builtins/**/*_tests/**/*.py"
- "conftest.py"
- "**/conftest.py"
rule: |
A test must have no side effects outside its own tmp dir. Never register a
real cron job, write into the operator's real ~/.kiro/crew or HOME, start
or reconfigure a gateway/service, or create files or directories in the
repo or anywhere else that outlive the run. These shapes have already
bitten us: a unit test registered a live cron job, test runs accumulated
stray directories under the developer's home, and an empty file a test
left at the repository root was committed and shipped to main.
A CHILD PROCESS INHERITS THE CWD, and pytest's CWD is the repository root.
A test that spawns one MUST pass `cwd=` pointing inside its own tmp dir,
or anything the child writes with a relative path lands in the repo. This
is the shape the paragraph above does not catch by reading the test: no
line says `touch` or `open(...,"w")`, the write happens in a grandchild
process, and the test can assert against its tmp dir and still pass while
the artifact sits at the repo root. So for any test that runs a child:
- pass `cwd=<a directory under tmp_path>` to any child that MAY CREATE a
file, and to every helper that spawns one. A read-only query is exempt
and sometimes has to be: `git check-ignore` run against the checkout is
answering a question about the checkout, and pointing it at a tmp dir
would test nothing.
- scope an assertion about a file the child MIGHT create to where that
child's CWD actually is, not to where you hope it wrote. An assertion
over `tmp_path` proves nothing about a child that ran somewhere else,
and a security test whose payload escapes its own assertion is worse
than no test, because it reports the guarantee it failed to check.
THE PROCESS WORKING DIRECTORY IS SHARED STATE. It is per-PROCESS, so under
xdist one test's `os.chdir` becomes every later test's starting directory on
that worker. FLAG a bare `os.chdir` in a test; `monkeypatch.chdir` reverts on
its own. This is not untidiness: a passing test's `tmp_path` is removed at that
test's teardown, so a test that chdirs into `tmp_path` and does not come back
leaves the worker in a DELETED directory, and `Path.cwd()` then raises
FileNotFoundError in every later test that reaches it — including from inside
production code (`taskrunner.TaskRunner.__init__` does `work_dir or Path.cwd()`).
Measured instance and its numbers: testing-conventions.md § Rules. The shape to
recognise in review is that it reads as "the suite is flaky" -- many files, each
passing in isolation -- rather than as one test missing one line.
A BACKGROUND WORKER BEATS EVERY FILESYSTEM CLEANUP, and this is the shape
neither paragraph above catches. A process singleton whose writer is a daemon
thread binds its directory ONCE, from whatever the first caller resolved. The
thread then outlives that test and re-creates the directory on its next flush —
AFTER the test's own tearDown removed it. `sel.py` is the worked case:
`SecurityEventLog._init_locked` captures `_default_dir()` and `_flush_batch`
opens with `mkdir(parents=True, exist_ok=True)`, which left one stray directory
behind on every run of a suite whose tests all cleaned up correctly. FLAG a test
that hands a PER-TEST directory to a subsystem with a background thread, task or
timer; the fix is a session-scoped directory that belongs to no individual test,
never tidier cleanup. Same family: a bare `MagicMock` config reads TRUTHY, so
patching `KiroCrewConfig.load` with one starts whatever subsystem is gated on
`cfg.<x>.enabled` and resolves `Path(cfg.local_dir)` to a RELATIVE path in the
repo; and a sleeper child (`python -c "import time; time.sleep(30)"`) whose
kill/wait sits on the happy path instead of in a `finally` or `addCleanup`.
A SECURITY ANCHOR IS NOT A DATA PATH. Some module-level values are built FROM
the real home precisely so they can refuse access to it — `security`'s
extract-into-trust-root pattern, `kiro_usage_api`'s credential-store paths.
Redirecting one to a tmp dir so a test can be isolated makes that test assert
against a pattern that no longer matches the thing it protects. FLAG it: stub
the READER, never move the anchor. The mirror-image defect is equally real —
handing a runtime-resolved path to a home-anchored matcher, which passes only
while the suite is reading the operator's REAL home and reports a guarantee it
never checked.
Know which floor you are standing on — it is NOT the same everywhere:
- The ROOTDIR `conftest.py` is the HOST-MUTATION FLOOR and applies to both
testpaths. It pins $XDG_CONFIG_HOME and the launchd paths, blocks
host service mutation, pins KIROCREW_HOME per test (with
`config.paths._resolved_home` reset, since resolving the home CREATES it
and can run the legacy migration), pins the import-time `~/.kiro`
bindings via `_isolate_shared_kiro_paths`, scrubs the inherited
shell-preload and exported-function variables `name_grant` refuses on
(`BASH_ENV`/`ENV`/..., `BASH_FUNC_*`), pins the SEL default dir
session-wide, redirects `tempfile`'s base with residue reported,
restores the session CWD in a `tryfirst` teardown hook before fixture
finalizers run, and fails the run on residue at the repository root.
- `test/conftest.py` adds ~40 MORE autouse fixtures, and it applies ONLY to
`test/`. Tests under `src/kiro_crew/apps/builtins/**/tests/` see the
rootdir conftest plus that app's own
`tests/conftest.py` where one exists (`auto_improvement`,
`code_review_sage`, `spec_builder` have one; the other apps do not), and
`aws_control/crew/runtime/container_tests/` sees the rootdir conftest
plus its own.
So a test there gets the host floor -- which now includes the data home,
the import-time `~/.kiro` bindings, the SEL dir, the subagent registry,
the model-download block and the agent-state sidecar -- but NOT the
suite-specific isolation (the Slack thread-state reset, the model-window
cache, the platform-context reset, the reasoning-effort globals, the
OPTIONS registries, …). FLAG a test in those trees that relies on one of
THOSE without arranging it itself.
- `~/.kiro` is a SEPARATE isolation axis from the data home: it is
kiro-cli's own machine-wide home, shared with the real installed agent,
so `~/.kiro/settings/mcp.json` is the LIVE agent's MCP server list. A new
module-level `Path.home()` binding in `src/kiro_crew` must be added to
`_SHARED_KIRO_PATHS` or excluded with a reason —
`test/test_host_isolation_floor.py` fails otherwise. That ratchet covers the
IMPORT-TIME shape only: a lazy resolver such as `config.paths.kiro_home()`
still names the operator's real `~/.kiro`, because the floor pins neither
`Path.home()` nor `$HOME`, so a test reaching one of those must isolate it
itself.
Assert against the tmp dir, not the real one, and clean up anything you
create. If a test genuinely needs a host-level effect, it must be opt-in
and named in the corresponding conftest allowlist with a comment saying
why. One scoped exception: the rootdir `conftest.py` keeps two per-user
caches across runs on purpose, the hypothesis example database
(`~/.cache/kirocrew/hypothesis`) and the bytecode mirror
(`~/.cache/kirocrew/pycache`), both under `$XDG_CACHE_HOME` when set. Those
two are not a test's side effect; nothing else in a conftest is exempt.
NEVER use bare `tempfile.mkdtemp()` or `tempfile.TemporaryDirectory()`
without cleanup. These create directories that survive the test run and
accumulate across runs, exhausting inodes — and inode exhaustion returns
ENOSPC to every other process on the machine while 90% of the BYTES are
still free, so it does not look like a disk problem. Use pytest's
`tmp_path` fixture, or pair every `mkdtemp()` with
`self.addCleanup(shutil.rmtree, path, ignore_errors=True)` ON THE LINE
AFTER IT. An `rmtree` in `tearDown` is NOT equivalent and is the shape that
actually leaks: `unittest` skips `tearDown` entirely when `setUp` raises,
so it leaks on every setUp failure — the failing run nobody is watching
closely. The rule is: if you create it, you must register its destruction
in the same scope. `ignore_errors=True` also SWALLOWS a cleanup that could
not finish, so it is not evidence the directory is gone.
NEVER use relative `Path("src/...")` or bare string paths to read source
files from a test. Under pytest-xdist, workers may change CWD, making
relative paths non-deterministic. Always anchor to the repo root via
`_REPO_ROOT = Path(__file__).resolve().parents[1]` (for test/ files) or
the equivalent number of parent hops for deeper test directories, then
use `_REPO_ROOT / "src/kiro_crew/..."`. This pattern is already
established in test_builtin_app_assets.py, test_platform_compat.py, and
test_skill_home_paths.py.
- id: tests-are-deterministic
blocking: true
file-patterns:
- "test/**/*.py"
- "packages/**/tests/**/*.py"
- "src/kiro_crew/apps/builtins/**/tests/**/*.py"
- "src/kiro_crew/apps/builtins/**/*_tests/**/*.py"
- "conftest.py"
- "**/conftest.py"
rule: |
A test must give the same verdict on every run, on every platform, in any
order and beside any neighbour. The suite runs `-n auto --dist loadgroup`
on Linux, macOS and Windows runners under load, so a test that is only
usually right reds unrelated pull requests. The contract is
`docs/system-specs/common/testing-conventions.md` § Determinism contract
(D1-D12, named on each item below); each shape below has burned this
repository before.
FLAG, on added or changed test lines:
1. (D1) A fixed sleep (`time.sleep(N)` / `await asyncio.sleep(N)` with
N > 0) used as a barrier before an assertion: "long enough for the
other side to get there". Wait on the state, event or future the
assertion reads, under a bounded deadline that raises naming what it
last saw. A sleep before an ABSENCE assertion is a barrier too unless
a positive signal first proved the other side reached the point where
it would act (the waiter registered, the product's own tick counter
reached N): without one the negative passes for the trivial reason.
2. (D3) A sleep that exists to make two timestamps differ, or an ORDER
assertion between records whose order comes from a stamp read off a
clock the test did not set. Windows' `time.time()` ticks ~15.6 ms
through Python 3.12 and some filesystems store mtimes in whole
seconds, so the stamps can tie. Set the stamps, assert the order
strictly (an exact list or `<`, not `>=`, which also accepts the
tie), and pin a time-sorted output's tie-break with an equal-stamp
pair. Do not flag a `<=` / `>=` on an invariant a tie satisfies
(start <= finish), or an order of stamps the product mints strictly
increasing.
3. (D2) A clock read at module level (`NOW = time.time()`) compared with
a value production derives from its own live clock. Either both sides
read one clock or neither does.
4. (D5) A `datetime.now()`, `date.today()` or `time.localtime()` read at
test time in an expectation, when the product stamps in another zone
or the two reads can straddle a midnight the test does not control.
Read the zone the product reads, and freeze the instant. A
`time.localtime(<fixed instant>)` that mirrors a product defined in
local time is correct; do not flag it.
5. (D7) An UPPER bound on a measured wall or CPU duration, a rate or a
sample count (`assert elapsed < 0.5`, "about 125 samples"). Assert the
work, the schedule or the order. Do not flag: a LOWER bound that proves
a deadline or backoff was honoured ("did not fire early") with a margin
of at least one clock tick; a bound relative to a span the test
measured itself; an existing complexity guard's thread-CPU budget kept
at its original constant.
6. (D8) An await, `join` or `communicate` the test itself must unblock,
with no timeout. On Windows a hang kills the xdist worker and aborts
the run; bound it so a miss fails by name at that line. A literal bound
on a condition wait (`wait_for`, `join`, `communicate`, a poll
deadline) is NOT flagged when its expiry fails the test loudly. Flag a
timeout only when the diff RAISES a literal, raises a named ceiling
without a cited measurement, or makes the pass depend on time elapsing
(a sleep standing in for a sync).
7. (D4) Sequence equality over a `set`, a dict built from one, `listdir` /
`iterdir` / `glob`, `as_completed` iteration, or side effects appended
in completion order, without `sorted()` or a `set` / `Counter`
comparison. `gather`'s return list is in argument order; do not flag
it.
8. (D6) `os.urandom` or the module-level `random.*` feeding an assertion,
instead of `random.Random(SEED)`.
9. (D9) A literal TCP port passed to a real bind or listen, or a
bind-close-return port handed to a listener that could bind port 0 and
report the port it got. A port number used only as data (a config
value, a fake socket's address, a URL under test) is not flagged.
10. (D10) A non-loopback network call that is not stubbed at the seam
the product calls.
11. (D2, D11) `setattr` or `patch` that rebinds a stdlib clock or sleep
for the whole worker (`time.time`, `time.monotonic`,
`time.perf_counter`, `time.sleep`), including through an alias such
as `"<mod>.time.monotonic"`, where `<mod>.time` is the stdlib module
itself: every event loop and thread in the worker reads it. Replace
the module-under-test's own `time` binding with a namespace that
delegates every other name to the real module. Also any in-process
`importlib.reload` of a shared module (load a private copy with
`importlib.util.spec_from_file_location` under a unique name,
registered under that name in `sys.modules` before `exec_module`,
never under the real name), and a
`sys.modules` eviction without restoring both the entry and the
parent package's attribute in the same scope.
12. (D11) A NEWLY ADDED autouse fixture that requests the shared
`monkeypatch` (use `_floor_monkeypatch`), or a bare
`monkeypatch.undo()` in a test body (scope the patch with
`monkeypatch.context()`).
Allowed (do NOT flag):
- a sleep inside a stub that simulates slow work while the test waits
on a signal;
- the interval of a bounded poll that re-reads the asserted state and
raises at its deadline (D1);
- a sleep that IS the subject, with the schedule asserted;
- a sleep inside a string literal: a spawned stand-in's keep-alive
payload (`"import time; time.sleep(120)"`) or source text fed to a
scanner;
- a named `UPPER_CASE` lost-run ceiling as testing-conventions defines
it (sized from a cited measurement, at most half the module's
`pytest.mark.timeout`, which the file may raise with its derivation);
- a line carrying `# flake-ok: <reason>` with a concrete reason.
A fix to a flaky test is held to the same bar. A retry, a rerun marker, a
skip, an xfail, a longer sleep, a raised timeout or a weakened assertion is
never the fix, except a module `pytest.mark.timeout` raised with its
derivation so a measured lost-run ceiling fits, or a too-tight bound
replaced by a NAMED lost-run ceiling sized from a cited measurement. FLAG
the rest on every path this rule covers (`a-ratchet-may-only-tighten`
covers the same loosening under `test/`).
- id: top-level-imports
blocking: false
file-patterns:
- "src/kiro_crew/**/*.py"
rule: |
All imports must be at the top of the file, not inside functions or
methods. In-method imports make dependencies hard to trace, break IDE
navigation, hide circular-import issues until runtime, and can make test
mock patches target the wrong module namespace.
Exceptions:
- TYPE_CHECKING blocks: `if TYPE_CHECKING: from ...` (zero runtime cost).
- Genuine circular-import avoidance — add a `# circular import` comment
explaining why.
- A deliberately deferred import that `no-new-work-on-gateway-boot-path`
requires, or an import-weight deferral a test pins, with a comment naming
the reason. The blocking boot-path rule outranks this advisory one.
- Optional dependencies: `try: import foo except ImportError: foo = None`
- id: harness-parity
blocking: true
file-patterns:
- "src/kiro_crew/acp/**/*.py"
- "src/kiro_crew/providers/**/*.py"
- "src/kiro_crew/platform/**/*.py"
- "src/kiro_crew/config/loader.py"
- "src/kiro_crew/config/loader_*.py"
- "src/kiro_crew/session.py"
- "src/kiro_crew/session_parts/*.py"
- "src/kiro_crew/subagent.py"
- "src/kiro_crew/subagent_parts/*.py"
- "src/kiro_crew/sandbox.py"
- "src/kiro_crew/sandbox_leaves.py"
- "src/kiro_crew/sandbox_tiers.py"
- "src/kiro_crew/sandbox_precreate.py"
- "src/kiro_crew/sandbox_seals.py"
- "src/kiro_crew/sandbox_aliases.py"
- "src/kiro_crew/sandbox_staging.py"
- "src/kiro_crew/sandbox_workspace.py"
- "src/kiro_crew/sandbox_argv.py"
- "src/kiro_crew/sandbox_delegation.py"
- "src/kiro_crew/sandbox_probe.py"
- "src/kiro_crew/sandbox_unavailable.py"
- "src/kiro_crew/sandbox_wrap.py"
- "src/kiro_crew/sandbox_cgroup.py"
- "src/kiro_crew/sandbox_slice.py"
- "src/kiro_crew/sandbox_rlimit.py"
- "src/kiro_crew/sandbox_spawn.py"
- "src/kiro_crew/sandbox_plan.py"
- "src/kiro_crew/sandbox_launcher.py"
- "src/kiro_crew/sandbox_launcher_program.py"
- "src/kiro_crew/sandbox_launcher_parts/*.py"
- "src/kiro_crew/sandbox_seatbelt.py"
- "src/kiro_crew/acp_backends.py"
- "src/kiro_crew/mcp_hot_reload.py"
- "src/kiro_crew/agent_sdk/backends.py"
- "src/kiro_crew/agent_sdk/backends_launch.py"
- "src/kiro_crew/agent_sdk/backends_mcp.py"
- "src/kiro_crew/agent_sdk/backends_members.py"
- "src/kiro_crew/agent_sdk/backends_models.py"
- "src/kiro_crew/agent_sdk/backends_routing.py"
- "src/kiro_crew/agent_sdk/backends_sessions.py"
- "src/kiro_crew/agent_sdk/backends_turns.py"
rule: |
Kiro Crew drives ONE first-class agent harness — kiro-cli
(ACP_BACKEND_KIRO, spelled "") — and ADAPTS the others (the
ACP_BACKEND_CLAUDE seam, KAS, and any bring-your-own harness). An added
harness may only adapt itself to the seams the Kiro harness already runs
through. It may not move, widen, generalize, or add a branch to them. The
invariant ids below are defined in
docs/system-specs/modules/harness-parity.md; cite the id in the finding.
The mechanical shapes are already gated on added lines by
scripts/check_harness_parity.py, so do NOT re-report them. Report only
what a regex cannot see:
- H13 — additive at the seam. Registering a harness must be a v1 addition
at platform/interfaces.py:ProviderRegistry with no CONTRACT_VERSION
bump. FLAG a change that puts a new conditional, a new required
argument, a new awaited step, or a new failure mode on the KIRO
construction path in service of an adapter — including one that reads
as harmless refactoring (hoisting a kiro-specific step into a shared
helper, replacing an explicit kiro branch with a table lookup, or
making a kiro-only default parameter mandatory). The test is not "does
it still work for kiro", it is "did the kiro path change at all".
- H14 — the ABC is the contract. A capability the session layer reads off
a provider must be declared on providers/base.py:LLMProvider with a
safe default. FLAG a change that adds a hasattr/getattr probe on the
kiro path to accommodate an adapter, or that leaves a new capability
reachable only on AcpProvider so a missing attribute silently reads as
False for the adapter.
- H9/H10 — no lowest-common-denominator. FLAG a change that collapses a
per-harness literal (spawn argv construction, PROTOCOL_VERSION, client
capabilities, the pre-spawn agent materialization, the --model pin) into
one form every harness accepts. Downgrading the kiro session to make an
adapter fit is the defect, even when every existing test still passes.
- H1/H3 — Kiro is the floor. FLAG a change that makes the kiro harness
conditional on an edition, a feature flag, an env var, or a registry
lookup, or that makes an unusable persisted acp_backend raise instead of
degrading to kiro with a logged reason. The exceptions are H17 and the
enterprise floor (D6), both under Allowed; still FLAG the selection gate
itself raising, or a refusal that reaches agent.acp_backend,
agent.member_acp_backend, an explicit spawn_run(backend=) override, or
any session that is not the pinned crewmate's own DM or worker.
- H6/H7 — capability grants. A new capability predicate must be membership
in a named ACP_BACKENDS_* set (defined in agent_sdk/backends.py or a backends_* owner,
re-exported by agent_sdk/backends.py and acp/types.py), and every existing
harness's membership must be an explicit decision in the diff. FLAG a
new predicate that grants a capability to a harness the PR never
mentions. For is_kiro_cli specifically the failure is OPEN — it makes
sandbox.wrap_argv SKIP Kiro Crew's own seatbelt in favour of the
harness's internal one — so treat a grant to any non-kiro harness as a
security finding.
Allowed (do NOT flag):
- The ACP_BACKEND_CLAUDE / _is_claude seam and its existing
negative call sites. They predate this rule, the whole-tree backlog is a
non-failing report by design, and converting them is a separate change.
- A pre-existing negative test on a line the PR merely moved or reindented.
- An adapter-only module (acp/kas_*.py and equivalents) that is entirely
additive and reachable only when its harness is selected.
- Widening the acp_backend config enum to admit a preview harness: the
enum is the value-SURVIVAL domain and selectability is gated separately
(H4). Omitting it there is the bug, not including it.
- H17: a crewmate's own harness pin (agents.<name>.acp_backend) that
this gateway cannot start refuses that crewmate's DM chat and workers
with CrewmateHarnessUnavailable instead of degrading to kiro. The owner
chose fail-closed for this one value: running the crewmate on a harness
it was moved away from is what the pin exists to prevent. The refusal is
the pre-gate check crewmate_backend_pin, evaluated as the crew_backend
argument of select_provider_backend before the gate runs; for any other
session it returns None and changes nothing, so it is not an H13 change
to the kiro construction path.
- D6 (rfc-crew-enterprise-edition.md): in an ENTERPRISE build the floor
is KAS, not kiro. The owner chose KAS as the one harness an enterprise
build keeps, so there the kiro harness is selectable only when the
remote policy allows it, and an unusable persisted acp_backend degrades
to KAS with a logged reason. The edition is read ONLY from the
build-time constant (kiro_crew.edition.is_enterprise()), never from
config, an env var or the platform context, so the selection gate stays
free of a context read (H3). A KAS that is proven unable to start on
the route it would take refuses the gateway start (enterprise boot,
naming the fix) instead of falling back to kiro. Still FLAG any of this
reaching an oss build, the edition read from anything but that
constant, the selection gate raising, or a silent fall back to kiro in
an enterprise build.
- id: memory-store-seam
blocking: true
file-patterns:
- "src/kiro_crew/context.py"
- "src/kiro_crew/context_assembly/**/*.py"
- "src/kiro_crew/memory.py"
- "src/kiro_crew/vector_memory.py"
- "src/kiro_crew/vector_memory_*.py"
- "src/kiro_crew/vector_memory_runtime/**/*.py"
- "src/kiro_crew/suggestions.py"
- "src/kiro_crew/tips.py"
- "src/kiro_crew/task_executor.py"
- "src/kiro_crew/task_planner.py"
- "src/kiro_crew/history_consolidation.py"
- "src/kiro_crew/history_consolidation_*.py"
- "src/kiro_crew/messaging/**/*.py"
- "src/kiro_crew/subagent_manager/**/*.py"
- "src/kiro_crew/slack/**/*.py"
- "src/kiro_crew/telegram/**/*.py"
- "src/kiro_crew/discord/**/*.py"
- "src/kiro_crew/feishu/**/*.py"
- "src/kiro_crew/imessage/**/*.py"
- "src/kiro_crew/teams/**/*.py"
- "src/kiro_crew/webex/**/*.py"
- "src/kiro_crew/wecom/**/*.py"
- "src/kiro_crew/weixin/**/*.py"
- "src/kiro_crew/dashboard/chat_api/**/*.py"
- "src/kiro_crew/dashboard/chat_runner.py"
- "src/kiro_crew/dashboard/chat_turn/**/*.py"
- "src/kiro_crew/dashboard/handlers/**/*.py"
- "src/kiro_crew/dashboard/messaging_api/**/*.py"
- "src/kiro_crew/dashboard/file_api/**/*.py"
- "src/kiro_crew/dashboard/agent_admin/**/*.py"
- "src/kiro_crew/eval/runner.py"
- "src/kiro_crew/config/loader.py"
- "src/kiro_crew/config/loader_*.py"
- "scripts/check_memory_store_seam.py"
rule: |
A named memory store is a SILO: cfg.agents[<crew>].memory_store
(config/loader.py, the `memory_store` field, default "default") selects a
SEPARATE SQLITE FILE. A new store starts EMPTY by default. Content is never
copied or inferred automatically; explicit owner-selected copies follow the
exception below. So a memory read that does not name its store reads
the operator's own `default` store for a crew that configured otherwise,
and NOTHING GOES RED: the prompt is well-formed, the store exists, and the
content is plausible. The reader is the only detector.
The mechanical shapes are already gated by
scripts/check_memory_store_seam.py, on the lines a change touches — added
lines, plus the anchor of a deletion-only hunk, since REMOVING a
`memory_store=` keyword adds no line at all. The shapes it owns: a missing
`memory_store=` on the enclosing call, a store derived from `agent=`, a bare
string literal, a literal `memory_store=None` (omission spelled out, since
the consumer collapses None onto its v1 workspace arm), an unanchored reference
to the target methods, and `get_memory_for` / `get_lessons_for` called with
nothing or a literal None. Do NOT re-report those. Report only what an AST
walk cannot see:
- A NEW READ PATH the gate does not know about. The gate matches four
names. FLAG a change that reaches memory some other way — constructing a
MemoryStore or a vector index directly, adding a second context builder
entry point, or adding a resolver alongside get_memory_for — without
threading the store name through it. A read path the gate cannot see is
exactly the one that will be added without a store.
- THE WRONG NAMESPACE passed as the store. The silo key is the named store
and nothing else. FLAG a call that passes a workspace name, a member or
channel slug, a project directory, a session key, or a kiro agent name
into `memory_store=`. These read as plausible because several of them are
in scope at every call site, and the gate cannot tell a store name from
any other string.
- RESOLUTION DUPLICATED AT THE CALL SITE. The store is resolved once, by
config.loader.resolve_agent_bindings, and its result is passed by name.
FLAG a call site that indexes cfg.agents itself, re-implements the
fallback to config.default_memory_store, or resolves a store from an
agent name inline — the measured failure mode is a silent `default` with
requested_resolved=False, for exactly the crew that configured otherwise.
- THE TWO ROOTS CONFLATED. The markdown/FTS root and the vector file are
different paths and a per-store resolver has to reproduce both for the
`default` store: the markdown root is memory.workspace_dir(), which is
config_dir()/"workspace" (memory.py), and the vector file is
config_dir()/"memory.db" (vector_memory.py's `db_path or ...` default).
FLAG a change that returns config_dir() itself as a store's markdown
root, or that moves the default store's vector file: either one takes
every existing user's preferences.md, projects.md and history/ out from
under the consolidator and `kirocrew memory search`, with no error.
- IMPLICIT CONTENT TRANSFER INTO A NEW STORE. FLAG automatic copies, seeds
or backfills, and any fallback read of Global Memory or another store when
the selected store is missing or unreadable. Explicit owner-selected
copies must satisfy the allowed case below.
- THE GATE ITSELF WIDENED. FLAG an added exemption table or ALLOWLIST
(scripts/check_memory_store_seam.py has none today; a reintroduced one
is the widening), a rule made conditional, or a `# memory-store-ok:`
marker whose reason does not survive reading — the reason exists so a
reviewer can decide whether the
call really has no store to name.
Allowed (do NOT flag):
- An explicit owner-authorized copy that names both source and destination,
copies only user-selected records, records source provenance, preserves
existing destination records, and leaves ownership and store bindings
unchanged. This does not authorize automatic inheritance, fallback reads
or shared private stores.
- The pre-existing unconverted call sites. The whole-tree backlog is a
non-failing report by design, pinned per rule by
test/test_memory_store_seam.py, and converting them is separate work.
- A call site that names the store and ALSO passes `agent=`. The two are
independent: `agent=` selects the kiro-cli mode, `memory_store=` selects
the silo, and the store being explicit is the point.
- `memory_store=cfg.default_memory_store` or
`memory_store=bindings.memory_store_name`. Reading the default store on
purpose is a legitimate answer; naming it is what makes it reviewable.
- `ContextBuilder.get_memory_for(ws_name)` / `get_lessons_for(ws_name)`
holding a WORKSPACE name. That parameter is `workspace`, resolved through
config.loader.workspace_dir_for. Both resolvers now also take a separate
`memory_store=` keyword, which wins when it names a non-default store.
A store name handed to the POSITIONAL workspace argument is still the
wrong-namespace bug (an unmapped workspace falls back to
config_dir()/"workspace", the default markdown root).
- Diff scoping is the standing enforcement mode. The whole-tree report
retains the operator heartbeat and evaluation coordinator calls, whose
unscoped spelling represents their Global context. Their exact backlog
is pinned by test/test_memory_store_seam.py; new unscoped call sites
remain forbidden. Whole-tree enforcement is not a promised rollout step.
- id: changelog-is-written-at-version-bump-only
blocking: true
file-patterns:
- "CHANGELOG.md"
rule: |
CHANGELOG.md is written ONLY when a version is bumped, and released
history in it is immutable. The spec for the section itself is
docs/build/changelog.md.
This rule exists because the file has already been destroyed once: a
docs commit on a release branch replaced CHANGELOG.md instead of
prepending to it, deleting the entire [0.2.0], [0.1.3] and [0.1.2]
sections (322 lines) and leaving one machine-generated section behind.
Nothing failed, no test covered it, and the loss was noticed only when a
user asked why the dashboard's Releases page had gone empty. A changelog
is append-only shipped history; a deletion in it is unrecoverable from
the artifact a user has installed.
- FLAG any change to CHANGELOG.md in a PR that is not a version bump or a
release cut. A feature, fix, refactor, test, or docs PR MUST NOT touch
this file — the release PR writes the section for everything that
shipped. If a PR author wants their change remembered, the commit
subject is the record.
- FLAG any diff that DELETES or MODIFIES a line inside an existing
released `## [X.Y.Z]` section. A release PR adds exactly one new
section at the top and leaves every pre-existing section
byte-identical. Treat a removed `## [` heading as a blocking finding on
its own, whatever the stated reason (merge-conflict resolution,
regeneration, "cleanup", branch divergence).
- FLAG a new `## [Unreleased]` section. There is no Unreleased section:
unshipped changes live in the commit log until a bump names them. Use
`git log --oneline <last-tag>..HEAD` to see what is pending.
`scripts/check_changelog_history.py` also refuses this mechanically, so
spend your attention on the section's CONTENT rather than re-deriving
this; report it only if the gate somehow did not.
- FLAG a section assembled from a commit dump — a bare list of commit
subjects, a "Bug Fixes (N total)" count, or a trailing "and N more
(see commit log)". That is not a changelog entry; it is the thing a
changelog entry exists to replace, and nobody reads it. A curated
`### Notable fixes` list of individually-named user-observable outcomes
is NOT a dump and is allowed — see docs/build/changelog.md for the line
between them.
- FLAG a heading that is not a plain release: `## [0.3.0-insider.9]`,
`## [0.3.0-rc.2]` and similar prerelease spellings must not appear.
A prerelease is a draft of its base version and is folded onto it by
src/kiro_crew/changelog.py; giving it its own heading puts a build
stamp in the reader's version archive. Mechanically refused by
`scripts/check_changelog_history.py` as well; a release branch writes
its section once, under the release's final heading.
Allowed (do NOT flag):
- A release PR that prepends one new `## [X.Y.Z] - YYYY-MM-DD` section
and, in the same commit, bumps the version files docs/build/release.md
lists (src/kiro_crew/__init__.py, pyproject.toml,
website/electron/package.json).
- Correcting a genuine factual error inside an already-shipped section,
when the PR body says that is what it is doing. Say it out loud; an
unexplained edit to shipped history is the defect this rule exists for.
- Porting an already-written section verbatim between main and a release
branch, where the diff adds a section and removes nothing.
- id: recorded-decisions-are-not-regressions
blocking: true
file-patterns:
- "docs/decisions/**"
- "website/src/**"
- "src/kiro_crew/**"
rule: |
docs/decisions/ is the team's record of product and design decisions a
person made: one immutable file per decision, indexed by its README. The
rules are in docs/decisions/README.md. This rule exists because a
recorded decision was reversed by a pull request that read as an ordinary
fix: a single nightly friction row asked for a longer button label, the
PR changed it, and nothing in review knew the short label had been chosen
on purpose. A decision that has to be re-made every time a report
disagrees with it was never recorded at all.
- FLAG any diff that EDITS, RENAMES or DELETES an existing file under
docs/decisions/ other than README.md. An entry is written once. A
change of mind is a NEW entry carrying a `Supersedes:` line that names
the old one, and the old file stays byte-identical.
`scripts/check_decisions_history.py` refuses this mechanically in Fast
Gate, so spend your attention on the next three points; report it only
if the gate somehow did not.
- FLAG a change to a user-facing label, wording, placement or behaviour
that an entry under docs/decisions/ records, when the PR adds no
superseding entry. Grep the directory for the control, key or
behaviour the diff touches. That the change closes an issue, answers a
friction report, satisfies a review finding or makes a test read
better is not a reason: an entry outranks all of those. A report that
collides with an entry is a feature request against a settled
decision, linked to the entry by its file path and left to a
maintainer; no fix is made from the report itself. Treat the reversal
as a regression, whatever the PR title says.
- FLAG a PR that carries an entry with a `Supersedes:` line, with or
without the code change it authorizes. This flag is by design: the one
way a decision changes is a dedicated PR carrying the superseding
entry, and a maintainer's override of this flag is what lets it land.
The entry is not a license to un-flag the code change beside it; the
maintainer's override is the approval, and it covers both.
- FLAG a new entry, superseding or not, whose Evidence links no
on-record artifact carrying the human decision it records — an issue,
a pull-request comment or a commit, checkable by anyone. "Decided in
chat" with no link is not evidence; the person restates the decision
on the PR and the entry cites that comment. An entry that decides on
the agent's own authority is refused.
- FLAG a new entry whose linked on-record statement was made by someone
not listed in MAINTAINERS.md. A contributor's stated preference, cited
by a contributor's own entry, is not a settled decision; a maintainer
restates it on the PR and the entry cites that comment instead.
Allowed (do NOT flag):
- Adding a new entry that names the person who decided and links the
evidence, with the matching index row in docs/decisions/README.md.
- Adding a founding entry (one with no `Supersedes:` line) that records
the outcome a person already decided AND links that person's on-record
statement of it, in the SAME PR as a change that RESTORES that outcome
after an unrecorded reversal. Nothing is being changed; the ledger is
catching up with what was decided, and the link is what keeps this
path from being a way to write a decision nobody made.
- Editing docs/decisions/README.md itself (index rows, rule wording).
- A change to a label, placement or behaviour that no entry records.
- id: recurring-defect-patterns
blocking: false
file-patterns:
- "src/kiro_crew/**/*.py"
rule: |
Defect patterns harvested from this repository's own fix history (each
appeared as a SERIES of shipped bugs, not a one-off). Flag a changed
line that re-introduces one of these classes as an advisory FINDING:
- A user-supplied or config-sourced STRING used directly in a boolean
context, especially for a security-relevant toggle: `bool("false")`
is True, so `if config.get("dangerously_skip_permissions"):` passes
for the string "false". Require an explicit typed comparison or a
real bool before the branch.
- A docstring or comment that CONTRADICTS the code below it (an
allowlist entry the docstring names but the code omits, a comment
saying "denies by default" above a loader that permits). Either the
prose or the code is wrong; both shipped as bugs here. Flag the
contradiction itself — do not guess which side is intended.
- A documented allowlist/denylist whose entries have no round-trip
assertion: when a diff adds or edits such a list alongside prose
(docstring, spec, comment) enumerating its members, expect a test
asserting each documented member is actually in the list.
This rule is maintained by the pattern-harvest loop (fix PRs propose
candidates in their "Pattern harvest" section; accepted ones land
here or in semgrep/). Sentinel-return misuse (str.find/rfind -1 in a
boolean context) is deliberately NOT listed: semgrep owns it
(semgrep/find-sentinel-truthiness.yaml).
- id: no-new-builtin-apps
blocking: true
file-patterns:
- "src/kiro_crew/apps/builtins/**"
- "src/kiro_crew/apps/manager_builtins.py"
- "src/kiro_crew/mcp_tools/apps.py"
- "src/kiro_crew/dashboard/server_internal_paths.py"
- "website/src/apps/**"
- "website/public/apps/**"
- "website/public/app-assets/**"
- "**/app.json"
- "src/kiro_crew/**/*.py"
- "website/src/**"
- "website/electron/**"
- "scripts/**"
- ".github/workflows/**"
rule: |
Kiro Crew accepts no new built-in app. The set that still ships is CLOSED
and is being EMPTIED: every app, first-party included, lives in a
dedicated GitHub repository listed in the official registry
(kirodotdev/KiroCrewApps, what the App Store's Discover page lists; the
catalog repo holds data only, never app code). The existing built-ins
move out under #26967
(docs/decisions/2026-11-01-kiro-crew-accepts-no-new-built-in-apps.md).
A built-in rides the wheel: it grows every user's install footprint,
cannot be uninstalled (only disabled), and couples the app's release and
fix cadence to Kiro Crew releases — the registry exists precisely so an
app can be listed, updated, and corrected with a catalog publish instead
of a client ship.
- FLAG any PR that adds a new app directory under
src/kiro_crew/apps/builtins/ (a new app.json), or re-adds an app that
has already moved out.
- FLAG a new app.json anywhere outside docs/app-kit/examples/ and test
fixtures (src/kiro_crew/tests_fixtures/, test/, website/src/test/).
- FLAG a new per-app page directory under website/src/apps/<app>/, or a
new per-app entry in the core frontend registries
(website/src/apps/builtinRegistry.ts, overlayRegistry.ts,
builtinIcons.tsx) or a new per-app asset directory under
website/public/app-assets/.
- FLAG a new per-app row in a core built-in table: BUILTIN_NAMES in
src/kiro_crew/apps/builtins/__init__.py, or the name sets in
src/kiro_crew/apps/manager_builtins.py.
- FLAG a new line of core code (backend, frontend, Electron shell,
scripts, CI workflows) that imports a specific app
(kiro_crew.apps.builtins.<app>, website/src/apps/<app>/) or hard-codes
a specific app id AS AN APP IDENTITY (an app-manager lookup, a manifest
or registry key, an app_id comparison), outside the built-in tables
listed in this rule that are being emptied and outside the app's own
directory. A word that also names a core subsystem (workflows,
channels, projects, meetings) is not an app id there. An app moves out
COMPLETELY: no part of it (backend, UI, scripts, CI, specs) stays in
core, and a capability it needs from core is a generic, app-agnostic
App Kit seam. Existing references are migration debt removed as each
app leaves; do not flag a line that only removes or narrows one.
- FLAG a new app-specific MCP tool in src/kiro_crew/mcp_tools/apps.py (a
tool named for, or serving, one app), or a new app-specific
internal-secret path row in
src/kiro_crew/dashboard/server_internal_paths.py.
- Point the author at a dedicated GitHub repository listed in the
official registry (kirodotdev/KiroCrewApps). A capability an app
cannot reach from outside core is an App Kit seam gap: the fix is a
generic seam every app can use, never the app in core. An explicit
maintainer decision recorded on the PR (the /ai-review override flow)
is the only exception — the default is closed.
- FLAG restoring a withdrawn built-in (the Board app) or un-hiding the
Channels app from the App Store (flipping "hidden": true in
src/kiro_crew/apps/builtins/channels/app.json). Both are deliberate
fork divergences an upstream sync must not undo.
Allowed (do NOT flag):
- Changes inside an EXISTING built-in app directory or its existing
page, registry entry or table row: fixes, features, tests, i18n,
refactors.
- Edits to an EXISTING core reference to a built-in (an import or app-id
use already on main) while that app still ships: only a NEW reference
is flagged.
- Deleting an existing built-in, or moving one OUT of the repo to the
registry — that is the direction this rule pushes. So is the migration
work for former built-ins under #26967: adopting a user's built-in
record onto its external source, moving generic, app-agnostic
infrastructure that lives under an app directory into core, and removing a row from any table
above as its app leaves.
- App Kit platform work: a generic seam, SDK surface or registry
mechanism any registry app can use.
- An app.json under docs/app-kit/examples/ or in a test fixture, and
edits to an existing app.json.
- A downstream edition contributing its own apps additively through the
extension seams; this rule covers this repository's tree.
- id: no-sync-store-call-from-a-coroutine
blocking: true
file-patterns:
- "src/kiro_crew/**/*.py"