Skip to content

Commit 777a084

Browse files
authored
feat(specs): 001-azure-aks-setup story spec (#98)
* feat(specs): add 001-azure-aks-setup spec with clarifications * docs(specs): trim dry-run, add partial-failure handling Dry-run removed from story: repo has no dry-run mode today; non-regression verified by unchanged AWS/local files plus one real run by a person with AWS access. Partial failure: commands stop, report what was created, never auto-delete; user reruns start (reuses existing) or runs cleanup. * docs(specs): add verification check and offline stand-in requirements FR-012: post-setup verification check reads live cluster and reports control plane + node group shape vs documented AWS setup; read-only. FR-013: offline checks via stand-in cloud commands covering command sequence, idempotent rerun, refusals, partial-failure reporting. SC-004: verification report is the acceptance evidence. * feat(azure): plan/tasks, manual try-out, T005 azure-common helper - .env: STACK_MODE gains aks; Azure settings block; k8s pinned 1.34 from the try-out (T001/T004) - specs/001-azure-aks-setup: plan.md, tasks.md, research.md, data-model.md, quickstart.md, azure-cli-contract; spec.md clarifications (spot deferred — 3-vCPU regional spot quota) and checklist - manual try-out: full-shape redeploy in eastus2 (5 pools, all regular per story-owner decision), 9/9 nodes Ready v1.34.10, gp2 StorageClass applied, MC_ node-resource-group name matched the exact prediction; torn down on owner's go — group gone in ~7 min, exact-name MC_ check gone, nothing left - infra/scripts/cluster/azure-common.sh (T005): STACK_MODE gate naming eks|local|aks, CLI <2.87.0 warning, four pre-checks (sign-in, subscription, location, all three VM sizes), deterministic names <name>-aks-<code> / sre-stack-<code>; happy path + refusal paths verified live against Azure - make lint: exit 0 - US1+ not started; blocked on gate:plan-approved * docs(constitution): add planning-phase principles VIII and IX VIII requires a hands-on command walkthrough with the user during plan research (research.md records actual runs and failures). IX requires plan.md and tasks.md to be built step by step with a reviewer in the loop instead of delivered finished. * docs(001): PR98 follow-ups — AD doc, cost-first allowance check, analyze fixes - docs/architectural-decisions.md: shared ADR record; AD-001 (keep gp2 alias on Azure), AD-002 (cost-first pool mode). AGENTS.md maps it. - spec: FR-014 machine-allowance check (spot preferred, regular family fallback, refuse naming shortfall); glossary entry; edge case; 09-09 clarification marked superseded. - plan: allowance-check facts; constitution rows VIII/IX. - contract: az vm list-usage pre-check, mode-aware spot flags, spot auto-taint exception, three new stand-in scenarios. - data-model: allowance rules, Spot-capable column semantics. - tasks: T023 helper allowance check (requires az vm list-usage hand-run first); T007/T010/T012 consume AZURE_POOL_MODE. - /speckit.analyze fixes: minimum-counts rule, auto-taint exclusion, IX attestation wording. * feat(aks): add allowance and permission pre-checks to azure-common (T023/T024) Phase 2b/2c amendments for specs/001-azure-aks-setup: - pre-check 5: az vm list-usage decides AZURE_POOL_MODE — spot when spot room >= 26, else regular when DSv5 >= 22 and FSv2 >= 4, else refuse naming the short family (FR-014, AD-002) - pre-check 2b: RBAC gate — Owner/Contributor at subscription scope, /, or parent MG; custom role only with */write or Microsoft.ContainerService/* actions; refuse otherwise - field shapes validated live against the sandbox subscription and recorded in research.md (constitution VIII) * feat(aks): setup script, gp2 StorageClass, STACK_MODE=aks (T006/T007) T006: infra/azure/gp2-storageclass.yaml — Azure disk CSI mirror of the local gp2 class (StandardSSD_LRS, WaitForFirstConsumer, Delete, expandable). T007: infra/scripts/cluster/setup-cluster-aks.sh — idempotent create of group > cluster+system pool > 4 workload pools (spot flags only when AZURE_POOL_MODE=spot) > kubeconfig > storageclass; contract \xc2\xa71 shapes, \xc2\xa73 partial-failure report, no auto-delete. Verified by a real signed-in run: cluster came up and a rerun skipped every existing resource. .env: STACK_MODE=aks for the manual run. * feat(aks): verify script + makefile dispatch checked (T008/T009/T010) T008: setup-cluster.sh STACK_MODE dispatch — aks execs setup-cluster-aks.sh, eks/local keep the original body, anything else refused (FR-006). T009: makefile inspect only; make --dry-run proves setup-cluster reaches the dispatcher (no edit). T010: verify-cluster-aks.sh — read-only; az aks show state/power, nodepool list vs data-model $3 table (system pool matched by mode, spot auto-taint excluded when mode=spot), namespaces FR-008. Live-tested against real Azure after a real T007 create/delete cycle: not-found path prints correct mismatches, rc=1. * test(azure): offline stand-in fake-az, fake-kubectl, 10-case runner (T011/T012) T011: fake-az.sh logs every full az call, answers from sourced scenario files with research-A7-shaped JSON (nodepool list built from the data-model $3 table); unknown command exits 127 so contract drift fails loudly. fake-kubectl.sh records kubectl calls into the same log (apply -> get succeeds, scenario PRE_SC flag). T012: run-offline-tests.sh runs the real setup script with the fake az first on PATH, one fresh sandbox per case; asserts exit codes, call log content/order, refusal text. All contract $2 US1 scenarios covered: happy, already-there, resume, not-signed-in, bad-location, missing-vm-size, spot-fits, spot-short, no-room, partial — 62 checks, 0 failed. Bugs the tests caught en route: fake-az missing list-locations branch, PRE_SC ignored by fake-kubectl, partial-report array name mismatch in setup-cluster-aks.sh (report now lists created/not-created correctly). * chore: drop stray truncated happy.s scenario file * fix(aks): partial-report done-list var mismatch; AD-003 spot auto-taint setup-cluster-aks.sh: _mark wrote _typeset_done but the report read _setup_done — partial runs showed only the system pool. One array now. AD-003: workload manifests need the Azure spot auto-taint toleration (recorded from the T010 review discussion). * docs(azure): contract \xc2\xa72 sync with the finished stand-in (T013) Fake kubectl recorded as part of the harness; scenario files are sourced shell knobs with answers shaped like research.md A7; unknown az command fails loudly. Runner rerun: 62 checks, 0 failed; make lint green. * perf(azure): replace stalled vm list-skus with az rest + parallel pre-checks az vm list-skus is a known 90 s-2 min CLI stall (client-side filter of a multi-MB response; azure-cli #31592/#30389). Size check now reads Resource Skus List (api-version 2021-07-01, $filter=location; the only supported server-side filter) via az rest and validates the three names locally — same --all semantics, refusal text unchanged.\xa0Contract \xc2\xa71 row synced same commit; fake-az grew the rest/ms.skus branch. Helper pre-checks 2b-5 (RBAC, locations, resource skus, usage) now run as four parallel az probes from the same sign-in point instead of serially, then evaluate results in contract order. Cache idea was dropped after testing (stale risk, no real win). Measured wall for the helper: ~15-17 s live vs 40-90+ s before. Offline suite rerun: 62 checks, 0 failed. * feat(aks): cleanup path, cleanup-mode helper, offline scenarios (T014-T016) cleanup-cluster.sh: with STACK_MODE=aks delete only the generated resource group ('nothing to clean' exits 0), then check the one exact predicted MC_ name and warn + exit non-zero if it lingers; eks/local code unchanged. azure-common.sh: new AZURE_CLEANUP=1 mode keeps sign-in and the generated names but skips the create-time probes, so teardown is never blocked by a changed quota, machine size, or role; refusals say 'Nothing was deleted'. makefile: the aks cleanup-cluster target skips the Amazon-only destroy-cluster-autoscaler/destroy-yace prerequisites. Offline tests: cleanup-full, cleanup-empty, and mc-lingers scenarios plus the MC_LINGERS stand-in knob; the runner asserts exactly one delete, no broad MC_* search, no other people's MC groups, and no create-time probes during teardown. bad-provider scenario dropped by story-owner decision; contract §2 synced and the departure recorded in plan.md. Also ticks T008, whose dispatch already shipped in 000a22d. * fix(aks): set executable bit on aks setup/verify scripts make setup-cluster exec'd setup-cluster-aks.sh via its shebang and failed with 'Permission denied'; the offline tests call both scripts through bash, so they never caught it. Found in the live end-to-end run on Azure. * ci: run azure offline tests on every PR (T025) * docs(aks): record AD-004, T019 drop, T025, and phase 5 evidence AD-004: Amazon non-regression is proven by the T017 diff survey plus T018's unchanged make lint, not a live AWS run (no Amazon access is available to this story); T019 is dropped accordingly. T025: the CI job running agent/tests/azure/run-offline-tests.sh landed in 3d008cf. Also records T017/T018 completion and the T025 task text. * docs(aks): phase 6 close-out (T020-T022) T020: quickstart Part B evidence collected — all four B1 refusals on a live signed-in session (logged out, fake subscription, fake location, STACK_MODE=nonsense on setup and cleanup), B2 real run + no-op rerun + verify report (SC-004), B3 offline tests, B4 double cleanup with the exact-name MC_ check gone. .env restored to demo values. T021: contract audit found one gap — az version is now listed in §1. T022: offline tests 80/80, make lint clean, research.md 15/15; quickstart 'Done when' list fully checked and T020-T022 ticked. * docs(sdlc): converge runs on the branch, before review and merge Upstream Spec Kit puts /speckit-converge after implement and before review (quickstart step 9: run implement and converge again until Converged, then open a PR). Our docs had it after merge on main, which cannot loop with implement on the same branch. framework.md is now v0.4: Step 6 converges on the branch (looping with /speckit-implement until Converged), Step 7 reviews and merges; the command table, labels-and-gates timeline, and the story-001 walkthrough follow. Post-merge discoveries become new story issues. * fix(aks): prove MG ancestry via inherited role assignments (T027) - azure-common: role assignment list gains --include-inherited so Azure returns only assignments effective at the subscription (its scope, root, and its real parent management groups); an unrelated management group can no longer pass the T024 check. - Offline proof: rbac-mg-ancestor and rbac-mg-unrelated scenarios; the stand-in mirrors Azure and emits a parent-scope row only when the flag is present. - Contract sections 1 and 2 synced; plan departures now log the az rest size-check switch, the parallel pre-check probes, and this fix. - T028/T029: data-model section 1 wording aligned; quickstart B3 gets the real offline-test command and expected summary line. Verified: offline tests 85 checks, 0 failed; make lint clean. * docs(aks): phase 8 convergence (T030-T032) - T030: mark regular-only spot decision superseded (FR-014/AD-002), fix Spot-capable column, update quickstart A6, track AD-003 exception to Constitution V in plan.md - T031: re-sync contract §1 (az account show --query id, kubectl get namespaces, drop uncompared provisioningState) - T032: remove unused _azure_refuse helper Verified: offline tests 85 checks 0 failed; make lint clean. * fix(aks): verify fails on pool and namespace mismatches (T033/T034) - T033: the embedded Python now exits with the mismatch count (min(fail, 254)) and the shell adds it to failures, so a cluster whose pools do not match the chosen mode no longer ends with 'report: 0 mismatch(es)' and exit 0. Reproduced with a forced spot/regular mismatch: four mismatches reported, rc 1. - T034: kubectl get namespaces failing or returning nothing is now a mismatch instead of an invisible empty list, so the FR-008 'cluster is still empty' check fails closed. Reproduced with a failing kubectl: report 1 mismatch(es), rc 1; happy path stays report 0, rc 0. Verified: offline tests 85 checks, 0 failed; make lint clean. * test(aks): drop dead vm list-skus stand-in branch (T037) No repo script calls az vm list-skus since the size check moved to az rest (Resource Skus List; plan.md departures). Removing it makes the stand-in unknown-command rule match contract section 1 again; the SIZES knob comment now points at the az rest answer. Verified: offline tests 85 checks, 0 failed; make lint clean. * docs(aks): phase 9-10 convergence records (T035-T037) - T035 dropped by story-owner decision: aks is the default STACK_MODE, recorded in plan.md 'Plan Departures' so convergence stops re-flagging T001's 'values untouched' line; .env comment states the default. - T036: quickstart B5 now matches T019/AD-004 (non-regression proven by the T017 diff survey plus T018 lint, not a live Amazon run). - Phase 9 T033/T034 and T037 ticked. Verified: offline tests 85 checks, 0 failed; make lint clean. * ci: harden offline-tests job permissions (T049) * fix(aks): address PR 98 review findings (T039-T049) - T039: gp2 StorageClass uses the Azure Disk CSI key skuName (disk.csi.azure.com ignores `type`; grounded in the driver's storage class parameter table). - T040: the always-regular system pool is counted in the allowance pre-check — DSv5 need 24 (22 workload + 2 system) and the spot branch also requires 2 DSv5 vCPU; contract, data-model and plan synced; scenario knobs sharpened and a new system-blocked scenario proves the refusal. - T041: verify reads [provisioningState, powerState.code] as a JMESPath multiselect list so TSV order is guaranteed (fake-az updated). - T042: contract section 1 escapes \$filter in the copied az rest URL. - T043: a reused cluster whose live kubernetesVersion differs from the .env pin warns and points at cleanup+setup; it never upgrades in place; data-model section 2 records the rule and already-there covers the warning. - T044: plan size pre-check wording -> filtered Microsoft.Compute/skus REST call per the T005/T023 speed pass. - T045: quickstart A5 drops the invalid --mode System argument. - T046: quickstart A8 applies infra/azure/gp2-storageclass.yaml instead of editing the tracked local manifest (US3 keeps it byte-identical). - T047: personal identifiers replaced with placeholders in research.md; the offline suite uses a fake subscription id. - T048: spec US3 aligns with AD-004 (diff survey + unchanged lint). - T049: ci.yml permissions/checkout hardening landed as 84a3e96. Verified: offline tests 90 checks, 0 failed; make lint clean. * test(aks): exercise verifier in offline suite (T038) Add verify scenarios to the no-cloud suite: fake az gains a POOL_MUTATIONS knob for malformed pool rows, fake kubectl gains FAKE_NAMESPACES/KUBECTL_NAMESPACES_FAIL, and the runner asserts verify-cluster-aks.sh exits non-zero for pool, namespace, and fail-closed kubectl mismatches while staying read-only. Contract section 2 lists the new scenarios in the same commit. * fix(aks): converge phase 12 findings (T050-T056) - T050: the allowance check reserves room only for missing pools and keeps the mode the existing workload pools already use — a full regular cluster reruns and verifies at zero free quota, a partial spot cluster never flips to regular; scenarios spot-resume, spot-resume-short, regular-full-resume, verify-ok-full-quota. - T051: cleanup tells a confirmed absent group from a failed read (non-zero exit, never "Nothing to clean") and checks the one exact MC_ name even when the main group is already gone; scenarios cleanup-read-error, cleanup-orphan-retry. - T052: spec US3 states the accepted outcome (Amazon/local files unchanged, repository checks pass) without command names; the live Amazon substitute stays referenced to AD-004. - T053: top-level make setup/cleanup route through the aks empty-cluster lifecycle only, with a make-time STACK_MODE refusal; runner cases make-setup/make-cleanup/make-refusal (no cloud). - T054: the machine-allowance answer is JSON parsed by field name; the stand-in returns the documented alphabetical TSV order for the legacy query so an order-dependent reader fails loudly. - T055: the verifier checks the kubectl context targets our cluster and inspects workloads, not just namespace names; scenarios verify-workload-extra, verify-wrong-context. - T056: setup separates confirmed / submitted-but-unconfirmed / not created (an async create with unreadable state is never "Not created"); a failed delete reports what remains or what could not be checked; scenarios partial-async, cleanup-delete-fail. Contract, data-model, quickstart and tasks sync in the same commit. Verified: offline tests 175 checks, 0 failed; make lint clean. * docs(sdlc): add session boundaries and handoff guidance (v0.5) Start a fresh agent session at major phase boundaries (specify/clarify and plan/tasks pairs keep together), support explicit task-range batching for implement, and require saved requirements, plan departures, updated tasks and a short handoff before a session ends. Guidance is grounded in the upstream Spec Kit docs/discussions cited in the section; session changes do not replace the approval gates. * fix(aks): converge phase 13 findings (T057-T060) * docs(constitution): bound convergence, compress wording (v1.3.1) Add Principle X "Converge to the Agreed Scope, Then Stop": a convergence task must trace to an approved requirement, success criterion, acceptance scenario, plan decision, or constitution rule; the spec's Edge Cases list closes at approval; only CRITICAL/HIGH findings append; one convergence round per story; tests sized to acceptance criteria. Stops the unbounded loop that took story 001 through seven convergence phases and roughly 200 offline checks for an agreed MVP. Compress the file to short-form wording (1,738 -> 1,476 words). Headings, MUST rules, paths, tags, numbers, and version metadata verified unchanged; independent semantic diff reported no differences. Version 1.3.0 -> 1.3.1 (PATCH: wording). Refs github/spec-kit#4269. * fix(aks): decide "absent" from the ARM error code, not stderr prose The three existence checks (cluster in the helper, cluster and node pool in setup) treated any stderr containing "not found" as NotFound. Unrelated failures carry that substring too (SubscriptionNotFound, an expired token "not found in cache"), so a broken read could pass as "absent" and start a duplicate create — the case T057 exists to prevent. az has no per-category exit code and --output never shapes errors, but it prints the ARM code structurally: "(<Code>)" on the first error line and a "Code: <Code>" line. _az_err_is_not_found matches only those, anchored and case-sensitive, for ResourceNotFound, ResourceGroupNotFound and AgentPoolNotFound. The fake az now emits SubscriptionNotFound with "not found" wording for CLUSTER_READ_FAIL / POOL_READ_FAIL, so the existing read-error scenarios guard the regression. Review: #98 (discussion r4013042421).
1 parent 94c38b8 commit 777a084

66 files changed

Lines changed: 5245 additions & 103 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
#!/bin/bash
22

33
# infra
4-
# STACK_MODE valid options eks | local
5-
STACK_MODE=eks
4+
# STACK_MODE valid options eks | local | aks (aks is the default)
5+
STACK_MODE=aks
66

77
# app-stack options are robot-shop | hotrod | all
88
APP_STACK=robot-shop
@@ -20,6 +20,13 @@ LOCAL_APP_SETUP_TIMEOUT=10m0s
2020
INOTIFY_MAX_USER_INSTANCES=8192
2121
INOTIFY_MAX_USER_WATCHES=524288
2222

23+
# Azure - AKS
24+
AZURE_SUBSCRIPTION_ID=
25+
# empty = documented fallback eastus2
26+
AZURE_LOCATION=
27+
# confirmed in the manual try-out (specs/001-azure-aks-setup/research.md)
28+
AKS_KUBERNETES_VERSION=1.34
29+
2330
# Namespaces
2431
MONITORING_NS=monitoring
2532
RABBITMQ_NS=rabbitmq

‎.github/workflows/ci.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@ jobs:
3535
# someone other than the author approved — the plan gate label.
3636
PROTECTED_OVERRIDE: ${{ (github.event_name == 'push' || contains(github.event.pull_request.labels.*.name, 'gate:plan-approved')) && '1' || '' }}
3737

38+
offline-tests:
39+
name: azure offline tests
40+
runs-on: ubuntu-latest
41+
permissions:
42+
contents: read
43+
steps:
44+
- uses: actions/checkout@v4
45+
with:
46+
persist-credentials: false
47+
48+
- name: Run the no-cloud Azure tests
49+
run: bash agent/tests/azure/run-offline-tests.sh
50+
3851
# TODO(agent-review): add the agent review job described in
3952
# docs/sdlc/framework.md section 6 once the harness and credentials are
4053
# decided (section 10, item 1). It posts ranked findings; it is not a gate.

‎.gitignore‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Universal
2+
.DS_Store
3+
Thumbs.db
4+
*.tmp
5+
*.swp
6+
.vscode/
7+
.idea/
8+
9+
# Logs and local run artifacts (never commit test output)
10+
*.log
11+
*.log*
12+
13+
# Offline test sandboxes (agent/tests/azure/run-offline-tests.sh)
14+
agent/tests/azure/.tmp-offline-*/
15+
16+
# Python inline helpers (no committed bytecode)
17+
__pycache__/
18+
*.pyc
19+
20+
# kubeconfig and local cluster state written by az/kubectl runs
21+
kubeconfig*
22+
*.kubeconfig
23+
.kube/
24+
25+
# NOTE: .env is deliberately tracked with demo-only values (AGENTS.md).
26+
# Do not add it here.

‎.specify/memory/constitution.md‎

Lines changed: 176 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,216 @@
11
<!--
22
Sync Impact Report
3-
- Version change: template → 1.0.0 (initial ratification)
4-
- Principles added: I. Re-runnable scripts · II. Pinned versions ·
5-
III. One configuration surface · IV. No secrets in git ·
6-
V. Workload placement contract
7-
- Sections added: Verification and Evidence · Development Workflow · Governance
8-
- Templates reviewed: plan-template.md (Constitution Check gate reads this
9-
file at plan time; no edits needed) · spec-template.md · tasks-template.md
3+
- Version change: 1.3.0 → 1.3.1 (PATCH: wording compressed, no rule changed)
4+
- Principles added: X. Converge to the Agreed Scope, Then Stop
5+
- Sections changed: all prose put in short-form wording; headings, MUST
6+
rules, paths, tags, numbers, and version metadata verified unchanged
7+
- Templates reviewed: plan-template.md (no edit needed; convergence
8+
boundary binds converge step and task list, not plan authoring);
9+
tasks-template.md (no edit needed; existing checklists stay)
1010
- Deferred: none
1111
-->
1212

1313
# sre-stack Constitution
1414

15-
These are the standing rules every story in this repository follows. They
16-
apply to humans and AI agents alike, on every harness. Operational
17-
corrections ("agents keep getting X wrong") live in `AGENTS.md`; rules live
18-
here.
15+
Standing rules every story here follow. Bind humans and AI agents, every
16+
harness. Operational corrections ("agents keep getting X wrong") live in
17+
`AGENTS.md`; rules live here.
1918

2019
## Core Principles
2120

2221
### I. Re-runnable Scripts
2322

24-
Every provisioning, deployment, and teardown script MUST resolve the repo
25-
root, source `.env`, and check before it creates or deletes. Running any
26-
lifecycle command twice in a row MUST be safe: the second run exits 0 and
27-
creates nothing new. Teardown MUST leave nothing behind that the setup
28-
created.
23+
Every provision, deploy, teardown script MUST resolve repo root, source
24+
`.env`, check before create or delete. Run any lifecycle command twice:
25+
MUST be safe — second run exit 0, create nothing new. Teardown MUST leave
26+
nothing setup made.
2927

30-
*Rationale:* the stack is created and destroyed on real clouds many times a
31-
week; a script that cannot be re-run is a script that will be hand-fixed
32-
under pressure.
28+
*Rationale:* stack made and destroyed on real clouds many times a week;
29+
script that cannot re-run get hand-fixed under pressure.
3330

3431
### II. Pinned Versions
3532

36-
Helm charts, container images, CLI tools, and Kubernetes versions MUST be
37-
pinned to explicit versions, and existing pins MUST be preserved unless the
38-
story's spec calls for the change. Helm installs use `*/chart-values/`
39-
files, never inline `--set` chains, except for one-off host wiring.
33+
Helm charts, container images, CLI tools, Kubernetes versions MUST pin to
34+
explicit versions, and existing pins MUST stay unless story spec call for
35+
change. Helm installs use `*/chart-values/` files, never inline `--set`
36+
chains, except one-off host wiring.
4037

41-
*Rationale:* unpinned installs make verification evidence unrepeatable and
42-
turn every rerun into a surprise upgrade.
38+
*Rationale:* unpinned installs make verification evidence unrepeatable,
39+
turn every rerun into surprise upgrade.
4340

4441
### III. One Configuration Surface
4542

46-
All tunable settings live in `.env`; the makefile and every script read
47-
from it. Nothing else is hand-edited to change behaviour. `.env` is
48-
deliberately tracked with demo-only values and MUST NOT be untracked.
49-
A story that introduces a secrets manager changes where `.env` values come
50-
from, not that `.env` is the surface.
43+
All tunable settings live in `.env`; makefile and every script read from
44+
it. Nothing else hand-edited to change behaviour. `.env` tracked on
45+
purpose with demo-only values and MUST NOT be untracked. Story that add
46+
secrets manager change where `.env` values come from, not that `.env` is
47+
surface.
5148

52-
*Rationale:* one file to read tells a person or an agent everything a
53-
deployment depends on.
49+
*Rationale:* one file to read tell person or agent everything a deployment
50+
depend on.
5451

5552
### IV. No Secrets in Git
5653

57-
Real credentials MUST NOT be committed. Demo credentials are allowed only
58-
in files listed in `agent/hooks/secrets-allowlist.txt`, and every entry
59-
there MUST carry a justification in `agent/policies/security-policy.md`.
60-
The secrets hook, git pre-commit, and CI enforce this; an allowlist entry
61-
or inline bypass marker is a reviewed change, not a workaround.
54+
Real credentials MUST NOT be committed. Demo credentials allowed only in
55+
files listed in `agent/hooks/secrets-allowlist.txt`, and every entry there
56+
MUST carry justification in `agent/policies/security-policy.md`. Secrets
57+
hook, git pre-commit, and CI enforce this; allowlist entry or inline bypass
58+
marker is reviewed change, not workaround.
6259

6360
### V. Workload Placement Contract
6461

65-
Every workload selects its node pool with `workload=app|persistent|o11y|loadgen`
66-
and tolerates the matching taint. Persistent volumes use the StorageClass
67-
named `gp2`. Any new cluster target (EKS, k3d, AKS, or later) MUST
68-
reproduce the same labels, taints, and storage class alias so that the
69-
application, observability, and scenario manifests deploy unchanged.
70-
71-
*Rationale:* the manifests are the product; cluster providers are
72-
interchangeable only while this contract holds.
62+
Every workload select node pool with `workload=app|persistent|o11y|loadgen`
63+
and tolerate matching taint. Persistent volumes use StorageClass named
64+
`gp2`. Any new cluster target (EKS, k3d, AKS, later) MUST reproduce same
65+
labels, taints, storage class alias so application, observability, scenario
66+
manifests deploy unchanged.
67+
68+
*Rationale:* manifests are product; cluster providers interchangeable only
69+
while this contract hold.
70+
71+
### VI. Specs Without Technical Detail
72+
73+
`spec.md` MUST NOT hold technical material: no code, no config snippets, no
74+
schemas, no commands, no implementation design. It say what needed, why,
75+
what must keep working — words newcomer understand. It name behaviour and
76+
outcomes, never technology used to deliver them. Implementation detail
77+
belong in `plan.md`, `tasks.md`, and change itself.
78+
79+
*Rationale:* spec read for approval by people who did not write code, and
80+
must survive change of technology. If it need technical background to
81+
judge, it describe solution instead of problem.
82+
83+
### VII. Plain Language Everywhere
84+
85+
Every document here — specs, plans, task lists, rationales, commit
86+
explanations, runbooks — MUST use simple everyday language with at least
87+
one concrete example, and MUST NOT lean on unexplained jargon. Technical
88+
term allowed only when no plain word work, and first use carry one-line
89+
explanation. Test: someone new to project read document alone and
90+
understand without asking anyone.
91+
92+
*Rationale:* documents exist to hand understanding from writer to reader.
93+
Jargon hand it only to people who already have it.
94+
95+
### VIII. Try It Before You Plan It
96+
97+
Story whose plan touch running infrastructure MUST get hands-on research
98+
before `plan.md` and `tasks.md` written. During Phase 0 (research.md),
99+
author walk key steps with real commands, together with person who will
100+
review plan:
101+
102+
- Before each command, author say in one or two sentences what it do and
103+
what could go wrong, then wait for go-ahead when command cost money,
104+
destroy something, or need environment user must provide.
105+
- Command runs. Actual output — every error, quirk, surprise — reported
106+
back and discussed before next step. Issues found this way shape plan;
107+
not discovered later by builder.
108+
- `research.md` record what was actually run and what happened, failures
109+
included, next to facts it cite. "The docs say" never substitute for "we
110+
ran it and here is what happened".
111+
- If no live run possible (cost, risk, missing environment), research.md
112+
say why and what replace it — dry run, `helm template`, sandbox — and
113+
plan approve that substitute.
114+
115+
*Rationale:* plan written only from documents inherit their silences.
116+
Cluster story only got workable plan because manual run-up surfaced issues
117+
no document mentioned. Errors found while walking steps with user are
118+
cheap; same errors found by builder mid-task are plan departures.
119+
120+
### IX. Plan In Steps, With the User in the Room
121+
122+
`plan.md` and `tasks.md` MUST be written in step-by-step conversation with
123+
person who will review plan — never delivered finished in one go. After
124+
each step, author:
125+
126+
- show what was just decided or written, plain language, with reason;
127+
- pause for questions, corrections, disagreement before next step;
128+
- carry agreed wording forward, so finished plan read as summary of shared
129+
walkthrough, not verdict handed down.
130+
131+
Test: reviewer read finished plan and recognise every part, because they
132+
saw each step as it was made. If live conversation not possible, same rule
133+
apply in writing — plan posted and agreed in reviewable chunks before
134+
final.
135+
136+
*Rationale:* approval mean understanding. Plan reviewer met only at end get
137+
rubber-stamped or rejected in bulk; plan built in steps get its real doubts
138+
raised while still cheap to fix.
139+
140+
### X. Converge to the Agreed Scope, Then Stop
141+
142+
Convergence — check of code against `spec.md`, `plan.md`, `tasks.md`
143+
before review — verify what was agreed. Not open-ended hunt for more edge
144+
cases. Exit criteria, agreed conditions for closing story:
145+
146+
- Convergence task MUST trace to something already agreed: functional
147+
requirement, success criterion, acceptance scenario, approved plan
148+
decision, or rule here. Work tracing to none of these is new story
149+
issue, never convergence task.
150+
- `spec.md` "Edge Cases" list closed at spec approval. Convergence MUST
151+
NOT add handling or checks for inputs, branches, failure modes spec do
152+
not name; extra hardening become new story.
153+
- Only CRITICAL and HIGH findings may become tasks. MEDIUM and LOW
154+
findings listed in convergence summary and filed as one follow-up story;
155+
they do not hold up this story's merge.
156+
- Story get one round of convergence work: append, implement, confirm. If
157+
confirming run still find CRITICAL or HIGH gap, spec or story size is
158+
wrong — stop and open new story instead of appending second round.
159+
- Tests sized to agreement: every requirement, acceptance scenario, named
160+
edge case get proving check, and convergence MUST NOT raise task for
161+
test coverage alone.
162+
163+
These rules bound new convergence work only; they do not license removing
164+
or weakening any existing check.
165+
166+
*Rationale:* review with no boundary always find another way code can fail,
167+
so "repeat until it reports Converged" never converge. First Azure story
168+
reached seven convergence phases and roughly 200 offline checks for what
169+
was agreed as MVP with four named edge cases. Software testing has
170+
established answer — agreement-based exit criteria: stop on requirement
171+
coverage and defect-severity threshold, not on rate new issues still found.
172+
Upstream Spec Kit hit same loop from lifecycle side (issue #4269: repeated
173+
converge runs duplicating tasks) and is adding prerequisite gate; rules
174+
above are scope half of that boundary.
73175

74176
## Verification and Evidence
75177

76-
- `make lint` runs for every change and its actual output is reported.
77-
"Should work" is not evidence; command output is.
78-
- Chart changes are checked with `helm template` or `helm lint` before any
79-
live run. Live cluster runs happen only when the story asks for them.
80-
- Cloud and library facts are grounded through the MCP servers listed in
178+
- `make lint` run for every change and its actual output reported. "Should
179+
work" is not evidence; command output is.
180+
- Chart changes checked with `helm template` or `helm lint` before any live
181+
run. Verification-time live runs happen only when story ask for them;
182+
planning-time live runs follow principle VIII.
183+
- Cloud and library facts grounded through MCP servers listed in
81184
`agent/policies/allowed-mcp-servers.md`, not from memory.
82-
- Verification steps a reviewer will run are written into the plan and
83-
their output is attached to the pull request (`evidence:attached`).
185+
- Verification steps reviewer will run written into plan and their output
186+
attached to pull request (`evidence:attached`).
84187

85188
## Development Workflow
86189

87-
The process is defined in `docs/sdlc/framework.md` and summarised in
88-
`AGENTS.md`. The rules that bind every story:
190+
Process defined in `docs/sdlc/framework.md`, summarised in `AGENTS.md`.
191+
Rules binding every story:
89192

90-
- A change starts from an accepted story (`intent:accepted`) and is sized
91-
to finish, including verification, in one or two days.
92-
- Spec, plan, and implementation are each approved by a named person who
93-
did not write them (`gate:spec-approved`, `gate:plan-approved`, human PR
94-
review). CI blocks code outside `specs/` until the plan label is present.
95-
- No `[NEEDS CLARIFICATION]` marker survives into an approved spec.
96-
- Departures from the plan are recorded in `plan.md` in the same commit
97-
that makes them.
98-
- Tests, hooks, lint allowlists, and CI are never weakened to make a change
99-
pass. Lint allowlists only shrink.
193+
- Change start from accepted story (`intent:accepted`), sized to finish,
194+
verification included, in one or two days.
195+
- Spec, plan, implementation each approved by named person who did not
196+
write them (`gate:spec-approved`, `gate:plan-approved`, human PR review).
197+
CI block code outside `specs/` until plan label present.
198+
- No `[NEEDS CLARIFICATION]` marker survive into approved spec.
199+
- Departures from plan recorded in `plan.md` in same commit that make them.
200+
- Tests, hooks, lint allowlists, CI never weakened to make change pass.
201+
Lint allowlists only shrink.
100202

101203
## Governance
102204

103-
This constitution supersedes any conflicting convention, comment, or
104-
habit. Every plan includes a Constitution Check; a violation is either
105-
fixed before implementation or justified in the plan's complexity table
106-
and accepted by the Architect.
205+
This constitution supersede any conflicting convention, comment, or habit.
206+
Every plan include Constitution Check; violation either fixed before
207+
implementation or justified in plan's complexity table and accepted by
208+
Architect.
107209

108-
Amendments are made by pull request to this file, approved by someone
109-
other than the author, and versioned semantically: MAJOR for removing or
110-
redefining a principle, MINOR for adding one or materially expanding
111-
guidance, PATCH for wording. When a mistake happens twice it becomes a
112-
rule here, a checklist line, or a hook.
210+
Amendments made by pull request to this file, approved by someone other
211+
than author, versioned semantically: MAJOR for removing or redefining
212+
principle, MINOR for adding one or materially expanding guidance, PATCH for
213+
wording. When mistake happen twice it become rule here, checklist line, or
214+
hook.
113215

114-
**Version**: 1.0.0 | **Ratified**: 2026-09-04 | **Last Amended**: 2026-09-04
216+
**Version**: 1.3.1 | **Ratified**: 2026-09-04 | **Last Amended**: 2026-09-11

‎AGENTS.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ AWS EKS or local k3d. Application code comes from upstream images.
1313
- `app/`, `monitoring/`, `scenarios/` contain workloads, tooling, and faults.
1414
- `agent/` contains source-of-truth policies, hooks, conformance tests, and loom.
1515
- `specs/<nnn>-<slug>/` contains each story's `spec.md`, `plan.md`, `tasks.md`.
16+
- `docs/architectural-decisions.md` is the shared ADR record (decision + why +
17+
what was given up); append new decisions there, one entry, newest last, and
18+
reference it by ID (AD-00n) from specs/plan/tasks instead of retelling.
1619
- `.specify/` (scripts, templates, manifests) and the Spec Kit commands in
1720
`.claude/skills/speckit-*`, `.agents/skills/speckit-*` (Codex),
1821
`.devin/skills/speckit-*`, and `.opencode/commands/speckit.*` are generated
@@ -56,9 +59,10 @@ Commands are spelled `/speckit-<verb>`; OpenCode spells them `/speckit.<verb>`.
5659
change outside the story's `specs/` folder before this label.
5760
4. Builder runs `/speckit-implement`; plan departures and reasons go into
5861
`plan.md` in the same commit. Attach verification output (`evidence:attached`).
59-
5. Agent review ranks findings; an independent human approves; squash-merge
60-
with the story's `specs/` folder.
61-
6. Run `/speckit-converge` on `main`; fix same-day gaps or file new stories.
62+
5. Builder runs `/speckit-converge` on the branch; if it appends tasks, run
63+
`/speckit-implement` and converge again until "Converged".
64+
6. Agent review ranks findings; an independent human approves; squash-merge
65+
with the story's `specs/` folder. Gaps found after merge become new stories.
6266

6367
Changes require an accepted story and `gate:plan-approved`; informational
6468
questions do not. Do not invent scope or weaken tests, hooks, lint, or CI.

0 commit comments

Comments
 (0)