Skip to content

Commit 29040cd

Browse files
8Dionysus8Dionysus
authored
Harden config district registry
Add root config registry validation, centralize config validation commands in config/AGENTS.md, and retire active Wave E/F naming from hygiene/config surfaces.
1 parent adb6d07 commit 29040cd

23 files changed

Lines changed: 447 additions & 73 deletions

‎config/AGENTS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ This card applies to `config/` and all descendants unless a nearer `AGENTS.md` n
88

99
`config/` holds source configuration for validators, generated mirrors, hygiene suites, and repository guardrails.
1010

11+
`config/registry.json` is the source map for this district. It must list every
12+
root `config/*.json` source, its consumer scripts, generated mirrors, and
13+
validation route.
14+
1115
## Read before editing
1216

1317
Read root `AGENTS.md`, then the relevant protocol doc for the config being changed.
@@ -19,15 +23,28 @@ Use the nearest README for local file purpose. Use source docs, schemas, generat
1923
- Config may drive checks; it must not silently become constitutional law.
2024
- When config changes a contract, update the human protocol and generated mirror together.
2125
- Do not loosen vocabularies, required surfaces, or generated freshness to avoid a failure.
26+
- Do not add unregistered root config JSON files.
27+
- Keep mechanic-owned seed config under the owning mechanic or part, not here.
2228

2329
## Validation
2430

2531
Run the narrowest relevant checks first. Usual checks for this district:
2632

2733
```bash
34+
python scripts/validate_config_registry.py
35+
python scripts/validate_hygiene_suite.py
2836
python scripts/validate_status_vocabulary.py
2937
python scripts/validate_generated_freshness.py
38+
python scripts/validate_agents_md_shape.py
3039
python scripts/validate_agents_mesh.py
40+
python scripts/build_agents_mesh_index.py --check
41+
python scripts/validate_agents_mesh_index.py
42+
```
43+
44+
For release-facing config changes, also run:
45+
46+
```bash
47+
python scripts/release_check.py
3148
```
3249

3350
If a listed validator is not present in the checkout yet, report that explicitly and run the closest available guardrail.

‎config/README.md‎

Lines changed: 43 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,55 @@
11
# Config District
22

3-
This directory holds repository-local configuration for center tooling and validation.
3+
`config/` holds repository-local source configuration for AoA center tooling.
4+
It is not a runtime secret store, not an `abyss-stack` configuration home, and
5+
not a place to smuggle mechanic-owned seed contracts back into the root.
46

5-
It is not a runtime secret store and not the configuration home for `abyss-stack`.
7+
Use this district when a setting governs repo-wide validators, generated
8+
mirrors, hygiene suites, release checks, or local guardrails. Mechanic-owned
9+
seed config belongs under the owning mechanic or part, such as
10+
`mechanics/<slug>/parts/<part>/config/`.
611

7-
Mechanic-owned seed config belongs in `mechanics/<slug>/config/`. Root config
8-
stays for repo-wide validators, hygiene, and release gates.
12+
## Source Map
913

10-
## Rules
14+
`config/registry.json` is the active map for this district. It lists each root
15+
config JSON file, its owner, source protocol, generated mirror, consumers, and
16+
validation route.
1117

12-
- Do not commit secrets.
13-
- Do not store workstation-local paths as public defaults.
14-
- Do not use config files to smuggle owner-local doctrine into the center.
15-
- Prefer explicit names that tell readers which script or validator consumes the config.
16-
- If a config change affects generated surfaces, update the matching documentation, validator, and tests.
18+
Every `config/*.json` file must be registered there. Do not add convenience
19+
aliases or workstation-local defaults.
1720

18-
## Current configs
21+
## Current Configs
1922

2023
| Surface | Consumed by | Role |
2124
|---|---|---|
22-
| `link_shape_hygiene.json` | Wave E hygiene validators and `generated/link_shape_hygiene.min.json` | local link repair rules, Markdown shape targets, status vocabularies, and generated freshness checks |
23-
| `agents_mesh.json` | Wave F AGENTS mesh validators and `generated/agents_mesh.min.json` | required local AGENTS-card coverage, shape headings, and compact mesh metadata |
24-
25-
## Before editing
26-
27-
1. Identify which script, validator, or generated surface consumes the config.
28-
2. Check whether the setting belongs to runtime infrastructure instead.
29-
3. Keep the default public-safe.
30-
4. Run the nearest validator.
25+
| `config/registry.json` | `scripts/validate_config_registry.py`, `tests/test_config_registry.py` | root config inventory and add-change contract |
26+
| `config/link_shape_hygiene.json` | hygiene validators and `generated/link_shape_hygiene.min.json` | local link repair rules, Markdown shape targets, status vocabularies, and generated freshness checks |
27+
| `config/agents_mesh.json` | AGENTS mesh validators and `generated/agents_mesh.min.json` | required local AGENTS-card coverage, shape headings, exemptions, and compact mesh metadata |
3128

32-
For `link_shape_hygiene.json`, the nearest validator is:
33-
34-
```bash
35-
python scripts/validate_hygiene_suite.py
36-
```
37-
38-
For `agents_mesh.json`, the nearest validators are:
29+
## Rules
3930

40-
```bash
41-
python scripts/validate_agents_md_shape.py
42-
python scripts/validate_agents_mesh.py
43-
python scripts/build_agents_mesh_index.py --check
44-
python scripts/validate_agents_mesh_index.py
45-
```
31+
- Do not commit secrets, tokens, credentials, private host paths, or local-only
32+
operator defaults.
33+
- Keep root config repo-wide. If a config only makes sense for one mechanic,
34+
move it to that mechanic's home.
35+
- When a config change affects generated surfaces, update the config, generated
36+
mirror, docs, validator, and tests together.
37+
- When adding a new root config JSON file, add it to `config/registry.json`
38+
before relying on it from scripts or release checks.
39+
- Config may drive checks; it must not silently become constitutional law.
40+
41+
## Add Or Change Route
42+
43+
1. Identify the consumer script, validator, generated surface, or release check.
44+
2. Confirm the setting belongs in root `config/`, not in `abyss-stack`,
45+
`mechanics/<slug>/`, or a sibling owner repo.
46+
3. Update `config/registry.json` with source refs, consumers, generated refs,
47+
validation commands, and `must_not_claim` boundaries.
48+
4. Update the human protocol or index named by the registry entry.
49+
5. Rebuild generated mirrors when the config feeds generated output.
50+
6. Run the narrow validators first, then the release gate if the change is
51+
release-facing.
52+
53+
## Validation
54+
55+
Use the validation lane in [`config/AGENTS.md`](AGENTS.md#validation).

‎config/link_shape_hygiene.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
{
22
"schema": "aoa.link_shape_hygiene.v1",
3-
"wave": "E",
43
"purpose": "Guard local links, Markdown shape, status vocabularies, generated freshness, and known link-drift repairs without becoming a source-of-truth layer.",
54
"protocol_ref": "docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md",
65
"index_ref": "docs/HYGIENE_GUARDRAIL_INDEX.md",
@@ -19,7 +18,6 @@
1918
"venv/**",
2019
"node_modules/**",
2120
"__pycache__/**",
22-
".wave_*_backups/**",
2321
"docs/traces/conflicts/**"
2422
],
2523
"ignore_schemes": [
@@ -718,6 +716,7 @@
718716
}
719717
],
720718
"validation_commands": [
719+
"python scripts/validate_config_registry.py",
721720
"python scripts/repair_known_link_drifts.py --check",
722721
"python scripts/validate_links.py",
723722
"python scripts/validate_markdown_shape.py",

‎config/registry.json‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
{
2+
"schema_version": "aoa_config_registry_v1",
3+
"purpose": "Map root configuration sources to their protocols, consumers, generated mirrors, and validation routes without turning config into doctrine or runtime state.",
4+
"owner": "Agents-of-Abyss",
5+
"district_ref": "config/README.md",
6+
"agents_ref": "config/AGENTS.md",
7+
"validation_commands": [
8+
"python scripts/validate_config_registry.py",
9+
"python scripts/validate_hygiene_suite.py",
10+
"python scripts/validate_agents_md_shape.py",
11+
"python scripts/validate_agents_mesh.py",
12+
"python scripts/build_agents_mesh_index.py --check",
13+
"python scripts/validate_agents_mesh_index.py",
14+
"python scripts/validate_generated_freshness.py",
15+
"python scripts/release_check.py"
16+
],
17+
"configs": [
18+
{
19+
"id": "config-registry",
20+
"path": "config/registry.json",
21+
"status": "active",
22+
"owner": "Agents-of-Abyss",
23+
"role": "root config district registry and add-change checklist",
24+
"source_ref": "config/README.md",
25+
"generated_refs": [],
26+
"consumers": [
27+
"scripts/validate_config_registry.py",
28+
"tests/test_config_registry.py"
29+
],
30+
"validation_commands": [
31+
"python scripts/validate_config_registry.py",
32+
"python -m pytest -q tests/test_config_registry.py"
33+
],
34+
"must_not_claim": [
35+
"runtime configuration authority",
36+
"secret storage",
37+
"mechanic-owned seed config ownership"
38+
]
39+
},
40+
{
41+
"id": "link-shape-hygiene",
42+
"path": "config/link_shape_hygiene.json",
43+
"status": "active",
44+
"owner": "Agents-of-Abyss",
45+
"role": "source config for local link repair, Markdown shape, status vocabulary, and generated freshness guardrails",
46+
"source_ref": "docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md",
47+
"index_ref": "docs/HYGIENE_GUARDRAIL_INDEX.md",
48+
"generated_refs": [
49+
"generated/link_shape_hygiene.min.json"
50+
],
51+
"consumers": [
52+
"scripts/hygiene_common.py",
53+
"scripts/repair_known_link_drifts.py",
54+
"scripts/validate_links.py",
55+
"scripts/validate_markdown_shape.py",
56+
"scripts/validate_status_vocabulary.py",
57+
"scripts/build_link_shape_hygiene_index.py",
58+
"scripts/validate_link_shape_hygiene_index.py",
59+
"scripts/validate_generated_freshness.py",
60+
"scripts/validate_hygiene_suite.py"
61+
],
62+
"validation_commands": [
63+
"python scripts/repair_known_link_drifts.py --check",
64+
"python scripts/validate_links.py",
65+
"python scripts/validate_markdown_shape.py",
66+
"python scripts/validate_status_vocabulary.py",
67+
"python scripts/build_link_shape_hygiene_index.py --check",
68+
"python scripts/validate_link_shape_hygiene_index.py",
69+
"python scripts/validate_generated_freshness.py",
70+
"python scripts/validate_hygiene_suite.py"
71+
],
72+
"must_not_claim": [
73+
"authored doctrine",
74+
"owner-local mechanic truth",
75+
"runtime configuration authority"
76+
]
77+
},
78+
{
79+
"id": "agents-mesh",
80+
"path": "config/agents_mesh.json",
81+
"status": "active",
82+
"owner": "Agents-of-Abyss",
83+
"role": "source config for required AGENTS-card coverage, shape headings, exemptions, and compact mesh metadata",
84+
"source_ref": "docs/AGENTS_MESH_PROTOCOL.md",
85+
"index_ref": "docs/AGENTS_MESH_INDEX.md",
86+
"generated_refs": [
87+
"generated/agents_mesh.min.json"
88+
],
89+
"consumers": [
90+
"scripts/agents_mesh_common.py",
91+
"scripts/validate_agents_md_shape.py",
92+
"scripts/validate_agents_mesh.py",
93+
"scripts/build_agents_mesh_index.py",
94+
"scripts/validate_agents_mesh_index.py"
95+
],
96+
"validation_commands": [
97+
"python scripts/validate_agents_md_shape.py",
98+
"python scripts/validate_agents_mesh.py",
99+
"python scripts/build_agents_mesh_index.py --check",
100+
"python scripts/validate_agents_mesh_index.py"
101+
],
102+
"must_not_claim": [
103+
"AGENTS card authorship",
104+
"constitutional override authority",
105+
"owner-local implementation truth"
106+
]
107+
}
108+
]
109+
}

‎docs/HYGIENE_GUARDRAIL_INDEX.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Hygiene Guardrail Index
22

3-
This index names the Wave E guardrails for link and shape hygiene.
3+
This index names the guardrails for link and shape hygiene.
44

55
The protocol lives in `docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md`. The machine-facing mirror lives in `generated/link_shape_hygiene.min.json`. The source config lives in `config/link_shape_hygiene.json`.
66

@@ -20,16 +20,16 @@ The protocol lives in `docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md`. The machine-fac
2020

2121
| Surface | Role |
2222
|---|---|
23-
| `docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md` | human law for Wave E hygiene |
23+
| `docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md` | human law for link and shape hygiene |
2424
| `docs/HYGIENE_GUARDRAIL_INDEX.md` | human index for guardrails |
2525
| `config/link_shape_hygiene.json` | source config for validators and generated mirror |
2626
| `generated/link_shape_hygiene.min.json` | compact machine-facing mirror |
27-
| `generated/agents_mesh.min.json` | required generated freshness target for Wave F AGENTS mesh |
28-
| `docs/traces/WAVE_E_HYGIENE_REPAIR_MANIFEST.json` | optional repair trace written by the apply script |
27+
| `generated/agents_mesh.min.json` | required generated freshness target for AGENTS mesh |
28+
| `docs/traces/HYGIENE_REPAIR_MANIFEST.json` | optional repair trace written by the apply script |
2929

3030
## What counts as success
3131

32-
Wave E is successful when:
32+
The hygiene guardrail is successful when:
3333

3434
1. no known stale link fragment remains;
3535
2. local Markdown links resolve to existing repository paths;

‎docs/LINK_AND_SHAPE_HYGIENE_PROTOCOL.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Link and Shape Hygiene Protocol
22

3-
This protocol is the Wave E guardrail for local links, Markdown shape, status vocabulary, generated freshness, and known link-drift repair inside `Agents-of-Abyss`.
3+
This protocol is the guardrail for local links, Markdown shape, status vocabulary, generated freshness, and known link-drift repair inside `Agents-of-Abyss`.
44

55
It does not author constitutional meaning. It keeps surfaces reachable, readable, and mechanically checkable so source-owned meaning can keep moving without losing its signs.
66

77
## Scope
88

9-
Wave E owns hygiene checks for these failure modes:
9+
This protocol owns hygiene checks for these failure modes:
1010

1111
- local Markdown links that point to files which no longer exist;
1212
- old flat links that should now point into a mechanic package or thematic district;
@@ -16,7 +16,7 @@ Wave E owns hygiene checks for these failure modes:
1616
- generated capsules that are hand-edited or stale;
1717
- known link repairs that remain tribal knowledge instead of becoming a checkable rule.
1818

19-
Wave E does not decide whether a doctrine is true. It only checks whether the map, shape, and generated mirrors still let an agent reach the stronger source.
19+
This protocol does not decide whether a doctrine is true. It only checks whether the map, shape, and generated mirrors still let an agent reach the stronger source.
2020

2121
## Ownership boundary
2222

@@ -83,7 +83,7 @@ The shape target list lives in `config/link_shape_hygiene.json`. Future files sh
8383

8484
Status words are small laws. They should not mutate casually.
8585

86-
Wave E validates status strings from configured JSON files against named vocabularies. This keeps `planted`, `landed`, `requested`, `operational`, and related words from becoming ornamental fog.
86+
The hygiene guardrail validates status strings from configured JSON files against named vocabularies. This keeps `planted`, `landed`, `requested`, `operational`, and related words from becoming ornamental fog.
8787

8888
Adding a new status requires updating the vocabulary config and explaining why the existing ladder could not express the state.
8989

@@ -93,7 +93,7 @@ Generated capsules may accelerate agent entry. They must not author meaning.
9393

9494
A generated surface is fresh only when its builder can reproduce it in `--check` mode. If a builder is absent and the surface is optional, the freshness check skips it. If the surface is required, absence fails.
9595

96-
The Wave E generated capsule is:
96+
The generated hygiene capsule is:
9797

9898
```text
9999
generated/link_shape_hygiene.min.json

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ python -m pytest -q
111111
| [`THEMATIC_DISTRICT_PROTOCOL`](THEMATIC_DISTRICT_PROTOCOL.md) | how old, historical, evidential, and transitional docs move into districts |
112112
| [`CURRENT_SURFACE_INDEX`](CURRENT_SURFACE_INDEX.md) | thin index of current docs root surfaces and districts |
113113
| [`LINK_AND_SHAPE_HYGIENE_PROTOCOL`](LINK_AND_SHAPE_HYGIENE_PROTOCOL.md) | how local links, Markdown shape, status vocabularies, and generated freshness stay checkable |
114-
| [`HYGIENE_GUARDRAIL_INDEX`](HYGIENE_GUARDRAIL_INDEX.md) | thin index of Wave E hygiene scripts, config, generated mirror, and traces |
114+
| [`HYGIENE_GUARDRAIL_INDEX`](HYGIENE_GUARDRAIL_INDEX.md) | thin index of hygiene scripts, config, generated mirror, and traces |
115115
| [`MECHANICS`](../mechanics/README.md) | the branch atlas for processes and engineering philosophy |
116116

117117

docs/traces/WAVE_E_HYGIENE_REPAIR_MANIFEST.json renamed to docs/traces/HYGIENE_REPAIR_MANIFEST.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,5 +66,5 @@
6666
"status": "applied"
6767
}
6868
],
69-
"schema": "aoa.wave_e_hygiene_repair_manifest.v1"
69+
"schema": "aoa.link_shape_hygiene_repair_manifest.v1"
7070
}

‎generated/AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,10 @@ center-side owner request packets.
4141
`generated/docs_thematic_index.min.json` is the compact machine-facing map of
4242
docs thematic districts.
4343
`generated/link_shape_hygiene.min.json` is the compact machine-facing mirror
44-
for Wave E link, Markdown shape, status vocabulary, and generated freshness
44+
for link, Markdown shape, status vocabulary, and generated freshness
4545
guardrails.
4646
`generated/agents_mesh.min.json` is the compact machine-facing mirror for the
47-
Wave F AGENTS-card mesh.
47+
AGENTS-card mesh.
4848
`mechanics/agon/parts/imposition-readiness/generated/agon_imposition_readiness.min.json` is the tracked Wave 0 readiness capsule for the center-owned Agon imposition gate.
4949
`mechanics/agon/parts/lawful-move-grammar/generated/agon_lawful_move_registry.min.json` is the tracked Wave III lawful
5050
move registry for the center-owned pre-protocol legal vocabulary.

‎generated/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ Root `generated/` contains only root-owned compact mirrors and indexes.
1717
| `mechanic_card_index.min.json` | compact reflection of mechanic package entry cards |
1818
| `owner_request_queue.min.json` | compact center-side owner request queue |
1919
| `docs_thematic_index.min.json` | compact map of docs thematic districts |
20-
| `link_shape_hygiene.min.json` | compact mirror of Wave E hygiene guardrails |
21-
| `agents_mesh.min.json` | compact mirror of Wave F AGENTS-card coverage |
20+
| `link_shape_hygiene.min.json` | compact mirror of link and shape hygiene guardrails |
21+
| `agents_mesh.min.json` | compact mirror of AGENTS-card coverage |
2222
| mechanic generated companions | generated companions under `mechanics/<slug>/generated/` |
2323

2424
## Rules

0 commit comments

Comments
 (0)