the-grimoire-cli 0.3.2 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/AGENTS.md +112 -112
- package/.agents/NAVIGATOR.md +193 -168
- package/.agents/VERSION +4 -4
- package/.agents/agents/INDEX.md +7 -7
- package/.agents/agents/verifier.md +50 -50
- package/.agents/commands/INDEX.md +11 -11
- package/.agents/commands/checkpoint.md +15 -15
- package/.agents/commands/grimoire.md +14 -14
- package/.agents/commands/onboard.md +56 -56
- package/.agents/commands/present.md +23 -23
- package/.agents/commands/verify.md +20 -20
- package/.agents/grimoire.manifest +18 -18
- package/.agents/rules/00-always.md +42 -42
- package/.agents/rules/05-code-quality.md +28 -28
- package/.agents/rules/10-working-process.md +31 -31
- package/.agents/rules/15-skills.md +27 -27
- package/.agents/rules/20-modes.md +41 -41
- package/.agents/rules/25-surgical-changes.md +29 -29
- package/.agents/rules/30-verification.md +36 -36
- package/.agents/rules/35-context-economy.md +41 -41
- package/.agents/rules/40-handoff.md +25 -25
- package/.agents/rules/45-presentation.md +35 -35
- package/.agents/rules/50-security.md +30 -30
- package/.agents/rules/60-commit-style.md +14 -14
- package/.agents/rules/INDEX.md +18 -18
- package/.agents/skills/INDEX.md +8 -8
- package/.agents/skills/README.md +1 -1
- package/.agents/skills/catalog.md +106 -106
- package/.agents/skills/find-skills/SKILL.md +142 -142
- package/.agents/stack/README.md +71 -66
- package/.agents/stack/desktop.md +36 -36
- package/.agents/stack/library.md +1 -1
- package/.agents/stack/web-app.md +32 -32
- package/.agents/standards/INDEX.md +23 -23
- package/.agents/standards/accessibility.md +50 -50
- package/.agents/standards/architecture.md +39 -39
- package/.agents/standards/attribution.md +39 -39
- package/.agents/standards/clean-code.md +121 -121
- package/.agents/standards/codex.md +69 -69
- package/.agents/standards/error-codes.md +41 -41
- package/.agents/standards/general.md +46 -46
- package/.agents/standards/guardrail-tests.md +40 -40
- package/.agents/standards/knowledge-management.md +35 -35
- package/.agents/standards/launch-security-checklist.md +45 -45
- package/.agents/standards/observability.md +35 -35
- package/.agents/standards/release-versioning.md +53 -53
- package/.agents/standards/requirements.md +75 -75
- package/.agents/standards/security-scanners.md +42 -42
- package/.agents/standards/testing-strategy.md +61 -61
- package/.agents/standards/typescript.md +19 -19
- package/.agents/standards/writing.md +58 -58
- package/.agents/tooling.json +20 -19
- package/LICENSE +1 -1
- package/README.md +139 -139
- package/bin/grimoire.mjs +667 -598
- package/package.json +32 -32
- package/templates/CLAUDE.md +7 -7
- package/templates/ci/ci.yml +49 -49
- package/templates/ci/sast.yml +44 -44
- package/templates/codex/INDEX.md +18 -18
- package/templates/codex/README.md +28 -28
- package/templates/codex/decisions/0000-template.md +36 -36
- package/templates/codex/decisions/INDEX.md +11 -11
- package/templates/codex/decisions/README.md +25 -25
- package/templates/codex/domain/INDEX.md +14 -14
- package/templates/codex/domain/README.md +10 -10
- package/templates/codex/evidence/0000-extraction-template.md +36 -36
- package/templates/codex/evidence/INDEX.md +11 -11
- package/templates/codex/evidence/README.md +15 -15
- package/templates/codex/reference/INDEX.md +11 -11
- package/templates/codex/reference/README.md +15 -15
- package/templates/codex/reference/confirmed-values.md +18 -18
- package/templates/codex/requirements/INDEX.md +11 -11
- package/templates/codex/requirements/README.md +22 -22
- package/templates/codex/requirements/addons/0000-template.md +35 -35
- package/templates/codex/requirements/base.md +36 -36
- package/templates/codex/requirements/changes/0000-template.md +39 -39
- package/templates/codex/resources/INDEX.md +11 -11
- package/templates/codex/resources/README.md +17 -17
- package/templates/codex/resources/manifest.md +11 -11
- package/templates/codex/runbooks/INDEX.md +9 -9
- package/templates/codex/runbooks/README.md +8 -8
- package/templates/codex/runbooks/incident-runbook-template.md +58 -58
- package/templates/gitignore-snippet.txt +10 -12
- package/templates/journal/backlog/README.md +18 -18
- package/templates/journal/memory/MEMORY.md +15 -15
- package/templates/journal/session/archive/.gitkeep +1 -1
- package/templates/journal/session/artifacts/.gitkeep +1 -1
- package/templates/journal/session/current.md +12 -12
- package/templates/lint/README.md +25 -25
- package/templates/lint/eslint.config.mjs +33 -33
- package/templates/lint/tsconfig.base.json +11 -11
- package/templates/local/AGENTS.local.md +33 -33
- package/templates/local/README.md +55 -55
- package/templates/tests/guardrail.invariants.test.ts +59 -59
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# evidence — index
|
|
2
|
-
|
|
3
|
-
Outputs of investigation, reverse-engineering, and extraction — the raw findings that feed `domain/`,
|
|
4
|
-
`reference/`, and `requirements/`. Every fact here is sourced.
|
|
5
|
-
|
|
6
|
-
| Entry | What it holds |
|
|
7
|
-
|---|---|
|
|
8
|
-
| `README.md` | The provenance discipline, in brief; points to `.agents/standards/codex.md`. |
|
|
9
|
-
| `0000-extraction-template.md` | Copy for each extraction run: source, method, sourced findings table. |
|
|
10
|
-
|
|
11
|
-
<!-- Extraction docs accumulate here as NNNN-<slug>.md. -->
|
|
1
|
+
# evidence — index
|
|
2
|
+
|
|
3
|
+
Outputs of investigation, reverse-engineering, and extraction — the raw findings that feed `domain/`,
|
|
4
|
+
`reference/`, and `requirements/`. Every fact here is sourced.
|
|
5
|
+
|
|
6
|
+
| Entry | What it holds |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `README.md` | The provenance discipline, in brief; points to `.agents/standards/codex.md`. |
|
|
9
|
+
| `0000-extraction-template.md` | Copy for each extraction run: source, method, sourced findings table. |
|
|
10
|
+
|
|
11
|
+
<!-- Extraction docs accumulate here as NNNN-<slug>.md. -->
|
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# evidence
|
|
2
|
-
|
|
3
|
-
Where investigation lands: reverse-engineering a legacy binary, extracting values from a vendor spec,
|
|
4
|
-
reading a database dump, recovering a protocol. These docs are the **paper trail** behind every
|
|
5
|
-
confirmed fact in `domain/`, `reference/`, and `requirements/`.
|
|
6
|
-
|
|
7
|
-
## Provenance discipline (in brief)
|
|
8
|
-
|
|
9
|
-
- Every finding cites its **source** — file + offset/record — and a **CONFIRMED | INFERRED** tag.
|
|
10
|
-
- What you couldn't recover is listed explicitly under "Not recovered" — silence is not a finding.
|
|
11
|
-
- No unsourced guesses. An `INFERRED` row stays inferred until a source confirms it.
|
|
12
|
-
- Never paste a real secret / PHI into an evidence doc; record its **location and purpose**, not its
|
|
13
|
-
value (see `resources/README.md` + `.agents/standards/codex.md`).
|
|
14
|
-
|
|
15
|
-
Copy `0000-extraction-template.md` per run. Full standard: `.agents/standards/codex.md`.
|
|
1
|
+
# evidence
|
|
2
|
+
|
|
3
|
+
Where investigation lands: reverse-engineering a legacy binary, extracting values from a vendor spec,
|
|
4
|
+
reading a database dump, recovering a protocol. These docs are the **paper trail** behind every
|
|
5
|
+
confirmed fact in `domain/`, `reference/`, and `requirements/`.
|
|
6
|
+
|
|
7
|
+
## Provenance discipline (in brief)
|
|
8
|
+
|
|
9
|
+
- Every finding cites its **source** — file + offset/record — and a **CONFIRMED | INFERRED** tag.
|
|
10
|
+
- What you couldn't recover is listed explicitly under "Not recovered" — silence is not a finding.
|
|
11
|
+
- No unsourced guesses. An `INFERRED` row stays inferred until a source confirms it.
|
|
12
|
+
- Never paste a real secret / PHI into an evidence doc; record its **location and purpose**, not its
|
|
13
|
+
value (see `resources/README.md` + `.agents/standards/codex.md`).
|
|
14
|
+
|
|
15
|
+
Copy `0000-extraction-template.md` per run. Full standard: `.agents/standards/codex.md`.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# reference — index
|
|
2
|
-
|
|
3
|
-
The confirmed-value layer: ground-truth tables, API/IPC catalogs, and big contract docs the **code
|
|
4
|
-
reads back**. ADRs that set `updates-confirmed-values: yes` update tables here in the same PR.
|
|
5
|
-
|
|
6
|
-
| Entry | What it holds |
|
|
7
|
-
|---|---|
|
|
8
|
-
| `README.md` | What belongs here vs `domain/`; the confirmed-values discipline. |
|
|
9
|
-
| `confirmed-values.md` | Ground-truth values (error codes, permission keys, enums, channel names). |
|
|
10
|
-
|
|
11
|
-
<!-- Add catalogs / contract docs alongside; list each here. -->
|
|
1
|
+
# reference — index
|
|
2
|
+
|
|
3
|
+
The confirmed-value layer: ground-truth tables, API/IPC catalogs, and big contract docs the **code
|
|
4
|
+
reads back**. ADRs that set `updates-confirmed-values: yes` update tables here in the same PR.
|
|
5
|
+
|
|
6
|
+
| Entry | What it holds |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `README.md` | What belongs here vs `domain/`; the confirmed-values discipline. |
|
|
9
|
+
| `confirmed-values.md` | Ground-truth values (error codes, permission keys, enums, channel names). |
|
|
10
|
+
|
|
11
|
+
<!-- Add catalogs / contract docs alongside; list each here. -->
|
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# reference
|
|
2
|
-
|
|
3
|
-
Confirmed-value tables and large runtime contracts the code depends on literally: error-code
|
|
4
|
-
catalogs, permission keys, shared enums, IPC/channel names, API/IPC catalogs, tenant/hospital config
|
|
5
|
-
tables. `domain/` explains *what things mean*; `reference/` pins *the exact values* both sides read
|
|
6
|
-
back.
|
|
7
|
-
|
|
8
|
-
## Confirmed-values discipline
|
|
9
|
-
|
|
10
|
-
- A value here is **ground truth** — code, tests, UI, and server agree on it. Treat a change as
|
|
11
|
-
breaking until proven otherwise.
|
|
12
|
-
- An ADR (`codex/decisions/`) that alters one sets `updates-confirmed-values: yes` and updates the
|
|
13
|
-
table **in the same PR** (the PR checklist enforces this).
|
|
14
|
-
- Each value carries its provenance (`CONFIRMED | INFERRED`, source) per `.agents/standards/codex.md`.
|
|
15
|
-
An `INFERRED` value is a lead, not a contract — confirm it before code relies on it.
|
|
1
|
+
# reference
|
|
2
|
+
|
|
3
|
+
Confirmed-value tables and large runtime contracts the code depends on literally: error-code
|
|
4
|
+
catalogs, permission keys, shared enums, IPC/channel names, API/IPC catalogs, tenant/hospital config
|
|
5
|
+
tables. `domain/` explains *what things mean*; `reference/` pins *the exact values* both sides read
|
|
6
|
+
back.
|
|
7
|
+
|
|
8
|
+
## Confirmed-values discipline
|
|
9
|
+
|
|
10
|
+
- A value here is **ground truth** — code, tests, UI, and server agree on it. Treat a change as
|
|
11
|
+
breaking until proven otherwise.
|
|
12
|
+
- An ADR (`codex/decisions/`) that alters one sets `updates-confirmed-values: yes` and updates the
|
|
13
|
+
table **in the same PR** (the PR checklist enforces this).
|
|
14
|
+
- Each value carries its provenance (`CONFIRMED | INFERRED`, source) per `.agents/standards/codex.md`.
|
|
15
|
+
An `INFERRED` value is a lead, not a contract — confirm it before code relies on it.
|
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
---
|
|
2
|
-
updated: <YYYY-MM-DD>
|
|
3
|
-
status: canonical
|
|
4
|
-
description: Ground-truth values the code reads back. Changed only via an ADR with updates-confirmed-values: yes, in the same PR.
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Confirmed values
|
|
8
|
-
|
|
9
|
-
Values the system treats as **ground truth** — error codes, permission keys, shared enums, channel /
|
|
10
|
-
IPC names, tenant configs. Changing one is breaking: it goes through an ADR
|
|
11
|
-
(`codex/decisions/`) with `updates-confirmed-values: yes`, updated here in the **same PR**.
|
|
12
|
-
|
|
13
|
-
| key | value | kind | source (file + offset) | CONFIRMED \| INFERRED |
|
|
14
|
-
|---|---|---|---|---|
|
|
15
|
-
| <e.g. ERR_AUTH_EXPIRED> | <value> | error code | `<file>:<offset>` | CONFIRMED |
|
|
16
|
-
|
|
17
|
-
<!-- One table per kind is fine (error codes, permissions, enums…). Never silently edit a value:
|
|
18
|
-
every change traces to an ADR. -->
|
|
1
|
+
---
|
|
2
|
+
updated: <YYYY-MM-DD>
|
|
3
|
+
status: canonical
|
|
4
|
+
description: Ground-truth values the code reads back. Changed only via an ADR with updates-confirmed-values: yes, in the same PR.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Confirmed values
|
|
8
|
+
|
|
9
|
+
Values the system treats as **ground truth** — error codes, permission keys, shared enums, channel /
|
|
10
|
+
IPC names, tenant configs. Changing one is breaking: it goes through an ADR
|
|
11
|
+
(`codex/decisions/`) with `updates-confirmed-values: yes`, updated here in the **same PR**.
|
|
12
|
+
|
|
13
|
+
| key | value | kind | source (file + offset) | CONFIRMED \| INFERRED |
|
|
14
|
+
|---|---|---|---|---|
|
|
15
|
+
| <e.g. ERR_AUTH_EXPIRED> | <value> | error code | `<file>:<offset>` | CONFIRMED |
|
|
16
|
+
|
|
17
|
+
<!-- One table per kind is fine (error codes, permissions, enums…). Never silently edit a value:
|
|
18
|
+
every change traces to an ADR. -->
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# requirements — index
|
|
2
|
-
|
|
3
|
-
What the system must **do**, as a tracked, IDed, versioned artifact. Protocol:
|
|
4
|
-
`.agents/standards/requirements.md`.
|
|
5
|
-
|
|
6
|
-
| Entry | What it holds |
|
|
7
|
-
|---|---|
|
|
8
|
-
| `README.md` | Rules of the road: stable ids, base-reflects-now, testable statements. |
|
|
9
|
-
| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
|
|
10
|
-
| `addons/0000-template.md` | Template for a new capability layered on the base. |
|
|
11
|
-
| `changes/0000-template.md` | Template for a change request modifying existing requirements. |
|
|
1
|
+
# requirements — index
|
|
2
|
+
|
|
3
|
+
What the system must **do**, as a tracked, IDed, versioned artifact. Protocol:
|
|
4
|
+
`.agents/standards/requirements.md`.
|
|
5
|
+
|
|
6
|
+
| Entry | What it holds |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `README.md` | Rules of the road: stable ids, base-reflects-now, testable statements. |
|
|
9
|
+
| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
|
|
10
|
+
| `addons/0000-template.md` | Template for a new capability layered on the base. |
|
|
11
|
+
| `changes/0000-template.md` | Template for a change request modifying existing requirements. |
|
|
@@ -1,22 +1,22 @@
|
|
|
1
|
-
# Requirements
|
|
2
|
-
|
|
3
|
-
The project's requirements as a tracked, referenceable artifact. Project-owned: `grimoire sync` never
|
|
4
|
-
touches this folder (seeded once by `grimoire init`). Full protocol:
|
|
5
|
-
`.agents/standards/requirements.md`.
|
|
6
|
-
|
|
7
|
-
## Files
|
|
8
|
-
|
|
9
|
-
| Path | Holds |
|
|
10
|
-
|---|---|
|
|
11
|
-
| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
|
|
12
|
-
| `addons/<id>-<slug>.md` | A new capability layered on the base (copy `addons/0000-template.md`). |
|
|
13
|
-
| `changes/<id>-<slug>.md` | A change request modifying existing requirements (copy `changes/0000-template.md`). |
|
|
14
|
-
|
|
15
|
-
## Rules of the road
|
|
16
|
-
|
|
17
|
-
- Every requirement has a stable id `REQ-<AREA>-<NNN>` — sequential per area, **never reused or
|
|
18
|
-
renumbered**. A removed requirement becomes `status: withdrawn`; its row stays.
|
|
19
|
-
- Cite the id in commits (`implements REQ-…`), test names, and the ADR that decided *how*.
|
|
20
|
-
- The **base always reflects now**; addons and CRs are the **audit trail** of how it got there.
|
|
21
|
-
Never change a requirement in `base.md` without a matching addon/CR file recording the diff.
|
|
22
|
-
- A requirement must be a **testable** statement. If it can't be verified, it isn't finished.
|
|
1
|
+
# Requirements
|
|
2
|
+
|
|
3
|
+
The project's requirements as a tracked, referenceable artifact. Project-owned: `grimoire sync` never
|
|
4
|
+
touches this folder (seeded once by `grimoire init`). Full protocol:
|
|
5
|
+
`.agents/standards/requirements.md`.
|
|
6
|
+
|
|
7
|
+
## Files
|
|
8
|
+
|
|
9
|
+
| Path | Holds |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `base.md` | The baseline — what the system must do **now**. Changed only via an applied addon/CR. |
|
|
12
|
+
| `addons/<id>-<slug>.md` | A new capability layered on the base (copy `addons/0000-template.md`). |
|
|
13
|
+
| `changes/<id>-<slug>.md` | A change request modifying existing requirements (copy `changes/0000-template.md`). |
|
|
14
|
+
|
|
15
|
+
## Rules of the road
|
|
16
|
+
|
|
17
|
+
- Every requirement has a stable id `REQ-<AREA>-<NNN>` — sequential per area, **never reused or
|
|
18
|
+
renumbered**. A removed requirement becomes `status: withdrawn`; its row stays.
|
|
19
|
+
- Cite the id in commits (`implements REQ-…`), test names, and the ADR that decided *how*.
|
|
20
|
+
- The **base always reflects now**; addons and CRs are the **audit trail** of how it got there.
|
|
21
|
+
Never change a requirement in `base.md` without a matching addon/CR file recording the diff.
|
|
22
|
+
- A requirement must be a **testable** statement. If it can't be verified, it isn't finished.
|
|
@@ -1,35 +1,35 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: ADDON-0000
|
|
3
|
-
title: <short addon title>
|
|
4
|
-
status: proposed # proposed | accepted | implemented | withdrawn
|
|
5
|
-
date: <YYYY-MM-DD>
|
|
6
|
-
extends: # REQ-… ids in base this builds on, if any
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# Addon ADDON-0000 — <short addon title>
|
|
10
|
-
|
|
11
|
-
A self-contained new capability layered on the base. Reviewable on its own. When it ships, fold its
|
|
12
|
-
rows into `base.md` and bump the base `version`; this file stays as history.
|
|
13
|
-
See `.agents/standards/requirements.md`.
|
|
14
|
-
|
|
15
|
-
## Why
|
|
16
|
-
|
|
17
|
-
What user need / opportunity this addresses. Link the PRD or discussion if any.
|
|
18
|
-
|
|
19
|
-
## New requirements
|
|
20
|
-
|
|
21
|
-
| id | statement | priority | status | acceptance | source |
|
|
22
|
-
|---|---|---|---|---|---|
|
|
23
|
-
| REQ-<AREA>-<NNN> | The system must <testable statement>. | must | proposed | <test or check> | this addon |
|
|
24
|
-
|
|
25
|
-
## Dependencies & impact
|
|
26
|
-
|
|
27
|
-
- **Builds on:** <REQ-… in base, or "none">
|
|
28
|
-
- **Touches:** <code areas, modules>
|
|
29
|
-
- **Decisions needed:** <ADR id(s) this spawns, if a design choice is required>
|
|
30
|
-
- **Confirmed values:** <does it add/change an error code, permission key, enum, channel? if so, the
|
|
31
|
-
ADR sets `updates-confirmed-values: yes` and the table updates in the same PR>
|
|
32
|
-
|
|
33
|
-
## Acceptance (addon-level)
|
|
34
|
-
|
|
35
|
-
How we know the whole addon is done — the set of checks across its requirements.
|
|
1
|
+
---
|
|
2
|
+
id: ADDON-0000
|
|
3
|
+
title: <short addon title>
|
|
4
|
+
status: proposed # proposed | accepted | implemented | withdrawn
|
|
5
|
+
date: <YYYY-MM-DD>
|
|
6
|
+
extends: # REQ-… ids in base this builds on, if any
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Addon ADDON-0000 — <short addon title>
|
|
10
|
+
|
|
11
|
+
A self-contained new capability layered on the base. Reviewable on its own. When it ships, fold its
|
|
12
|
+
rows into `base.md` and bump the base `version`; this file stays as history.
|
|
13
|
+
See `.agents/standards/requirements.md`.
|
|
14
|
+
|
|
15
|
+
## Why
|
|
16
|
+
|
|
17
|
+
What user need / opportunity this addresses. Link the PRD or discussion if any.
|
|
18
|
+
|
|
19
|
+
## New requirements
|
|
20
|
+
|
|
21
|
+
| id | statement | priority | status | acceptance | source |
|
|
22
|
+
|---|---|---|---|---|---|
|
|
23
|
+
| REQ-<AREA>-<NNN> | The system must <testable statement>. | must | proposed | <test or check> | this addon |
|
|
24
|
+
|
|
25
|
+
## Dependencies & impact
|
|
26
|
+
|
|
27
|
+
- **Builds on:** <REQ-… in base, or "none">
|
|
28
|
+
- **Touches:** <code areas, modules>
|
|
29
|
+
- **Decisions needed:** <ADR id(s) this spawns, if a design choice is required>
|
|
30
|
+
- **Confirmed values:** <does it add/change an error code, permission key, enum, channel? if so, the
|
|
31
|
+
ADR sets `updates-confirmed-values: yes` and the table updates in the same PR>
|
|
32
|
+
|
|
33
|
+
## Acceptance (addon-level)
|
|
34
|
+
|
|
35
|
+
How we know the whole addon is done — the set of checks across its requirements.
|
|
@@ -1,36 +1,36 @@
|
|
|
1
|
-
---
|
|
2
|
-
version: 0.1.0
|
|
3
|
-
updated: <YYYY-MM-DD>
|
|
4
|
-
status: canonical
|
|
5
|
-
description: Baseline requirements — what the system must do now. Changed only via an applied addon or change request.
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Requirements — baseline
|
|
9
|
-
|
|
10
|
-
The agreed requirements at the current accepted state. This file always reflects **now**. It changes
|
|
11
|
-
only when an addon (`addons/`) or change request (`changes/`) is applied — see
|
|
12
|
-
`.agents/standards/requirements.md` for the flow. Never edit a requirement here without a matching
|
|
13
|
-
addon/CR file recording the diff.
|
|
14
|
-
|
|
15
|
-
## How to read a row
|
|
16
|
-
|
|
17
|
-
`id` (stable `REQ-<AREA>-<NNN>`, never reused) · `statement` (one testable "the system must …") ·
|
|
18
|
-
`priority` (`must | should | could`) · `status` (`proposed | accepted | implemented | withdrawn`) ·
|
|
19
|
-
`acceptance` (the test or check that proves it) · `source` (who/what introduced it).
|
|
20
|
-
|
|
21
|
-
## Requirements
|
|
22
|
-
|
|
23
|
-
### AREA: <e.g. AUTH>
|
|
24
|
-
|
|
25
|
-
| id | statement | priority | status | acceptance | source |
|
|
26
|
-
|---|---|---|---|---|---|
|
|
27
|
-
| REQ-AUTH-001 | The system must <testable statement>. | must | accepted | `test/auth/...` or manual check | initial spec |
|
|
28
|
-
|
|
29
|
-
<!-- Add one section per area. Keep numbers sequential per area; never renumber or reuse an id.
|
|
30
|
-
A withdrawn requirement stays in the table with status: withdrawn — do not delete the row. -->
|
|
31
|
-
|
|
32
|
-
## Changelog (applied addons / CRs)
|
|
33
|
-
|
|
34
|
-
| date | id | kind | summary | base version after |
|
|
35
|
-
|---|---|---|---|---|
|
|
36
|
-
| <YYYY-MM-DD> | <ADDON-001 / CR-001> | addon \| change | <one line> | 0.1.0 |
|
|
1
|
+
---
|
|
2
|
+
version: 0.1.0
|
|
3
|
+
updated: <YYYY-MM-DD>
|
|
4
|
+
status: canonical
|
|
5
|
+
description: Baseline requirements — what the system must do now. Changed only via an applied addon or change request.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Requirements — baseline
|
|
9
|
+
|
|
10
|
+
The agreed requirements at the current accepted state. This file always reflects **now**. It changes
|
|
11
|
+
only when an addon (`addons/`) or change request (`changes/`) is applied — see
|
|
12
|
+
`.agents/standards/requirements.md` for the flow. Never edit a requirement here without a matching
|
|
13
|
+
addon/CR file recording the diff.
|
|
14
|
+
|
|
15
|
+
## How to read a row
|
|
16
|
+
|
|
17
|
+
`id` (stable `REQ-<AREA>-<NNN>`, never reused) · `statement` (one testable "the system must …") ·
|
|
18
|
+
`priority` (`must | should | could`) · `status` (`proposed | accepted | implemented | withdrawn`) ·
|
|
19
|
+
`acceptance` (the test or check that proves it) · `source` (who/what introduced it).
|
|
20
|
+
|
|
21
|
+
## Requirements
|
|
22
|
+
|
|
23
|
+
### AREA: <e.g. AUTH>
|
|
24
|
+
|
|
25
|
+
| id | statement | priority | status | acceptance | source |
|
|
26
|
+
|---|---|---|---|---|---|
|
|
27
|
+
| REQ-AUTH-001 | The system must <testable statement>. | must | accepted | `test/auth/...` or manual check | initial spec |
|
|
28
|
+
|
|
29
|
+
<!-- Add one section per area. Keep numbers sequential per area; never renumber or reuse an id.
|
|
30
|
+
A withdrawn requirement stays in the table with status: withdrawn — do not delete the row. -->
|
|
31
|
+
|
|
32
|
+
## Changelog (applied addons / CRs)
|
|
33
|
+
|
|
34
|
+
| date | id | kind | summary | base version after |
|
|
35
|
+
|---|---|---|---|---|
|
|
36
|
+
| <YYYY-MM-DD> | <ADDON-001 / CR-001> | addon \| change | <one line> | 0.1.0 |
|
|
@@ -1,39 +1,39 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: CR-0000
|
|
3
|
-
title: <short change title>
|
|
4
|
-
status: proposed # proposed | accepted | applied | rejected
|
|
5
|
-
date: <YYYY-MM-DD>
|
|
6
|
-
affects: # the REQ-… id(s) this change modifies
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# Change Request CR-0000 — <short change title>
|
|
10
|
-
|
|
11
|
-
A modification to one or more **existing** requirements. Records the diff old → new so the change is
|
|
12
|
-
auditable. When applied, update the affected rows in `base.md`, bump the base `version`, and log it in
|
|
13
|
-
the base changelog; this file stays as history. See `.agents/standards/requirements.md`.
|
|
14
|
-
|
|
15
|
-
## Reason for change
|
|
16
|
-
|
|
17
|
-
What changed in the world (new constraint, user feedback, regulation, a wrong assumption) that forces
|
|
18
|
-
this. Be factual.
|
|
19
|
-
|
|
20
|
-
## The change
|
|
21
|
-
|
|
22
|
-
| id | old statement | new statement |
|
|
23
|
-
|---|---|---|
|
|
24
|
-
| REQ-<AREA>-<NNN> | <the current statement> | <the revised statement> |
|
|
25
|
-
|
|
26
|
-
<!-- For a withdrawal: new statement = "(withdrawn — <reason>)" and set the row's status to withdrawn
|
|
27
|
-
in base.md (keep the id). -->
|
|
28
|
-
|
|
29
|
-
## Impact
|
|
30
|
-
|
|
31
|
-
- **Code/tests:** what must change to honor the new statement.
|
|
32
|
-
- **Decisions:** ADR id(s) this needs or supersedes.
|
|
33
|
-
- **Confirmed values:** if a ground-truth value changes (error code, permission key, enum, channel),
|
|
34
|
-
the linked ADR sets `updates-confirmed-values: yes` and the table updates in the **same PR**.
|
|
35
|
-
- **Downstream requirements:** other `REQ-…` affected by this change.
|
|
36
|
-
|
|
37
|
-
## Acceptance
|
|
38
|
-
|
|
39
|
-
The check that proves the new statement holds (and the old behavior is gone).
|
|
1
|
+
---
|
|
2
|
+
id: CR-0000
|
|
3
|
+
title: <short change title>
|
|
4
|
+
status: proposed # proposed | accepted | applied | rejected
|
|
5
|
+
date: <YYYY-MM-DD>
|
|
6
|
+
affects: # the REQ-… id(s) this change modifies
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Change Request CR-0000 — <short change title>
|
|
10
|
+
|
|
11
|
+
A modification to one or more **existing** requirements. Records the diff old → new so the change is
|
|
12
|
+
auditable. When applied, update the affected rows in `base.md`, bump the base `version`, and log it in
|
|
13
|
+
the base changelog; this file stays as history. See `.agents/standards/requirements.md`.
|
|
14
|
+
|
|
15
|
+
## Reason for change
|
|
16
|
+
|
|
17
|
+
What changed in the world (new constraint, user feedback, regulation, a wrong assumption) that forces
|
|
18
|
+
this. Be factual.
|
|
19
|
+
|
|
20
|
+
## The change
|
|
21
|
+
|
|
22
|
+
| id | old statement | new statement |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| REQ-<AREA>-<NNN> | <the current statement> | <the revised statement> |
|
|
25
|
+
|
|
26
|
+
<!-- For a withdrawal: new statement = "(withdrawn — <reason>)" and set the row's status to withdrawn
|
|
27
|
+
in base.md (keep the id). -->
|
|
28
|
+
|
|
29
|
+
## Impact
|
|
30
|
+
|
|
31
|
+
- **Code/tests:** what must change to honor the new statement.
|
|
32
|
+
- **Decisions:** ADR id(s) this needs or supersedes.
|
|
33
|
+
- **Confirmed values:** if a ground-truth value changes (error code, permission key, enum, channel),
|
|
34
|
+
the linked ADR sets `updates-confirmed-values: yes` and the table updates in the **same PR**.
|
|
35
|
+
- **Downstream requirements:** other `REQ-…` affected by this change.
|
|
36
|
+
|
|
37
|
+
## Acceptance
|
|
38
|
+
|
|
39
|
+
The check that proves the new statement holds (and the old behavior is gone).
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# resources — index
|
|
2
|
-
|
|
3
|
-
Raw materials the project draws on: datasets, vendor specs, dumps, external artifacts and snapshots.
|
|
4
|
-
The inputs to investigation (`evidence/`), not the conclusions.
|
|
5
|
-
|
|
6
|
-
| Entry | What it holds |
|
|
7
|
-
|---|---|
|
|
8
|
-
| `README.md` | What belongs here; large / secret / binary handling; the manifest rule. |
|
|
9
|
-
| `manifest.md` | Tracked index of every resource — including gitignored ones — with source + purpose. |
|
|
10
|
-
|
|
11
|
-
<!-- Add resources alongside this INDEX; list each in manifest.md. -->
|
|
1
|
+
# resources — index
|
|
2
|
+
|
|
3
|
+
Raw materials the project draws on: datasets, vendor specs, dumps, external artifacts and snapshots.
|
|
4
|
+
The inputs to investigation (`evidence/`), not the conclusions.
|
|
5
|
+
|
|
6
|
+
| Entry | What it holds |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `README.md` | What belongs here; large / secret / binary handling; the manifest rule. |
|
|
9
|
+
| `manifest.md` | Tracked index of every resource — including gitignored ones — with source + purpose. |
|
|
10
|
+
|
|
11
|
+
<!-- Add resources alongside this INDEX; list each in manifest.md. -->
|
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
# resources
|
|
2
|
-
|
|
3
|
-
Raw materials and external artifacts: datasets, vendor/API specs, database dumps, binary snapshots,
|
|
4
|
-
captured payloads — the inputs you reverse-engineer or extract from. Conclusions go in `evidence/`
|
|
5
|
-
and `reference/`; the raw stuff lives here.
|
|
6
|
-
|
|
7
|
-
## Large / secret / binary handling
|
|
8
|
-
|
|
9
|
-
- **Secret-bearing or PHI-bearing raw material** (dumps, captures, credential files) is **gitignored**
|
|
10
|
-
— it must never enter git history. Add the path to the project `.gitignore`.
|
|
11
|
-
- **Huge or binary** artifacts: keep out of the repo (or use the project's large-file mechanism);
|
|
12
|
-
don't bloat history.
|
|
13
|
-
- **Always keep a tracked `manifest.md`**: one row per resource — name, source/provenance, purpose,
|
|
14
|
-
and whether it's tracked or gitignored. The manifest is the durable record even when the bytes are
|
|
15
|
-
not in git, so a reader knows what exists and where to get it.
|
|
16
|
-
|
|
17
|
-
Never echo a secret / PHI from a resource into chat or agent output. See `.agents/standards/codex.md`.
|
|
1
|
+
# resources
|
|
2
|
+
|
|
3
|
+
Raw materials and external artifacts: datasets, vendor/API specs, database dumps, binary snapshots,
|
|
4
|
+
captured payloads — the inputs you reverse-engineer or extract from. Conclusions go in `evidence/`
|
|
5
|
+
and `reference/`; the raw stuff lives here.
|
|
6
|
+
|
|
7
|
+
## Large / secret / binary handling
|
|
8
|
+
|
|
9
|
+
- **Secret-bearing or PHI-bearing raw material** (dumps, captures, credential files) is **gitignored**
|
|
10
|
+
— it must never enter git history. Add the path to the project `.gitignore`.
|
|
11
|
+
- **Huge or binary** artifacts: keep out of the repo (or use the project's large-file mechanism);
|
|
12
|
+
don't bloat history.
|
|
13
|
+
- **Always keep a tracked `manifest.md`**: one row per resource — name, source/provenance, purpose,
|
|
14
|
+
and whether it's tracked or gitignored. The manifest is the durable record even when the bytes are
|
|
15
|
+
not in git, so a reader knows what exists and where to get it.
|
|
16
|
+
|
|
17
|
+
Never echo a secret / PHI from a resource into chat or agent output. See `.agents/standards/codex.md`.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# Resource manifest
|
|
2
|
-
|
|
3
|
-
One row per resource — tracked **and** gitignored. The durable record of what exists and where to get
|
|
4
|
-
it, even when the bytes aren't in git. Keep it current.
|
|
5
|
-
|
|
6
|
-
| resource | source / provenance | purpose | git status |
|
|
7
|
-
|---|---|---|---|
|
|
8
|
-
| `<path or name>` | <where it came from> | <what it's used for> | tracked \| gitignored |
|
|
9
|
-
|
|
10
|
-
<!-- For gitignored secret/PHI-bearing material: record location + purpose only here; the value lives
|
|
11
|
-
in the gitignored inventory, never in a tracked doc. -->
|
|
1
|
+
# Resource manifest
|
|
2
|
+
|
|
3
|
+
One row per resource — tracked **and** gitignored. The durable record of what exists and where to get
|
|
4
|
+
it, even when the bytes aren't in git. Keep it current.
|
|
5
|
+
|
|
6
|
+
| resource | source / provenance | purpose | git status |
|
|
7
|
+
|---|---|---|---|
|
|
8
|
+
| `<path or name>` | <where it came from> | <what it's used for> | tracked \| gitignored |
|
|
9
|
+
|
|
10
|
+
<!-- For gitignored secret/PHI-bearing material: record location + purpose only here; the value lives
|
|
11
|
+
in the gitignored inventory, never in a tracked doc. -->
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
# runbooks — index
|
|
2
|
-
|
|
3
|
-
The on-call answer to "production is broken — what now." One file per service, kept short and
|
|
4
|
-
runnable under stress. Required by the launch-security checklist
|
|
5
|
-
(`.agents/standards/launch-security-checklist.md`).
|
|
6
|
-
|
|
7
|
-
| Entry | What it holds |
|
|
8
|
-
|---|---|
|
|
9
|
-
| `incident-runbook-template.md` | Copy per service to `codex/runbooks/<service>.md`. |
|
|
1
|
+
# runbooks — index
|
|
2
|
+
|
|
3
|
+
The on-call answer to "production is broken — what now." One file per service, kept short and
|
|
4
|
+
runnable under stress. Required by the launch-security checklist
|
|
5
|
+
(`.agents/standards/launch-security-checklist.md`).
|
|
6
|
+
|
|
7
|
+
| Entry | What it holds |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `incident-runbook-template.md` | Copy per service to `codex/runbooks/<service>.md`. |
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# runbooks
|
|
2
|
-
|
|
3
|
-
The on-call answer to "production is broken — what now." One runbook per service, copied from
|
|
4
|
-
`incident-runbook-template.md` to `codex/runbooks/<service>.md`. Keep each short, current, and
|
|
5
|
-
runnable under stress — a runbook nobody can follow at 3am is worse than none.
|
|
6
|
-
|
|
7
|
-
Required by the launch-security checklist (`.agents/standards/launch-security-checklist.md`). The
|
|
8
|
-
highest-value section is "Common failure modes" — fill it in per service as incidents teach you.
|
|
1
|
+
# runbooks
|
|
2
|
+
|
|
3
|
+
The on-call answer to "production is broken — what now." One runbook per service, copied from
|
|
4
|
+
`incident-runbook-template.md` to `codex/runbooks/<service>.md`. Keep each short, current, and
|
|
5
|
+
runnable under stress — a runbook nobody can follow at 3am is worse than none.
|
|
6
|
+
|
|
7
|
+
Required by the launch-security checklist (`.agents/standards/launch-security-checklist.md`). The
|
|
8
|
+
highest-value section is "Common failure modes" — fill it in per service as incidents teach you.
|