Skip to content

Commit adb6d07

Browse files
8Dionysus8Dionysus
authored
Trim mechanics root docs
Trim mechanics root docs, fold alias law into artifact topology, and preserve package-local legacy/raw seed routes.
1 parent 46b77c7 commit adb6d07

4 files changed

Lines changed: 35 additions & 47 deletions

File tree

‎mechanics/ARTIFACT_TOPOLOGY.md‎

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -61,29 +61,23 @@ boundary. Examples:
6161
- Quest lifecycle schemas, quest projections, quest validators, and quest
6262
closure checks belong under `mechanics/questbook/`.
6363

64-
## No Root Aliases
64+
When a mechanic-owned artifact moves, update callers, validators, generated
65+
indexes, and docs to use the owning path directly; do not add root or flat
66+
package aliases as convenience copies.
6567

66-
Do not add new root-authored mechanic artifacts. Add them to the owning
67-
mechanic package and update callers, validators, generated indexes, and docs to
68-
use that path directly.
69-
70-
For part-based mechanics, do not recreate flat package aliases either. Use
71-
`mechanics/<slug>/artifact-map.json` as the receipt when old flat paths have
72-
been moved into part-local homes.
68+
Package-local `legacy/raw`, seed, and landing receipt districts are allowed
69+
when they preserve source lineage without becoming alternate active routes.
7370

7471
## Questbook
7572

76-
Questbook is a mechanic, not a TODO pile. The root `QUESTBOOK.md` stays a compact
77-
frontier index, and `quests/` stays the public item store. Quest source objects
78-
live in lane-first lifecycle directories such as `quests/center/triaged/`,
79-
`quests/agon/triaged/`, and `quests/experience/triaged/`; top-level
80-
`quests/AOA-Q-*` aliases are intentionally absent. The questbook package owns
81-
lifecycle, placement, closure, harvest, generated read models, and
82-
owner-routing rules.
83-
84-
Use quests when an obligation should survive the current diff as a public,
85-
reviewable game-object for agents. Do not use quests for private scratch work,
86-
temporary plans, or roadmap duplication.
73+
Questbook is the one intentional root-store exception: `mechanics/questbook/`
74+
owns quest lifecycle, placement, closure, harvest, generated read models, and
75+
owner-routing rules, while root `QUESTBOOK.md` stays a compact frontier index
76+
and `quests/` stays the public item store.
77+
78+
Use `quests/` only for public, reviewable obligations that should survive the
79+
current diff. Do not use it for private scratch work, temporary plans, or
80+
roadmap duplication.
8781

8882
## Validation
8983

‎mechanics/README.md‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -183,34 +183,13 @@ notes as substitutes for package-local truth.
183183
| [recurrence](recurrence/README.md) | [SELF_AGENCY_CONTINUITY](recurrence/docs/SELF_AGENCY_CONTINUITY.md), [COMPONENT_REFRESH_LAW](recurrence/docs/COMPONENT_REFRESH_LAW.md), [RECURRENCE_PRINCIPLE](recurrence/docs/RECURRENCE_PRINCIPLE.md), [PARTS](recurrence/PARTS.md) |
184184
| [checkpoint](checkpoint/README.md) | [CHECKPOINT_LAW](checkpoint/docs/CHECKPOINT_LAW.md), [CHECKPOINT_OWNER_BOUNDARY](checkpoint/docs/CHECKPOINT_OWNER_BOUNDARY.md), [PARTS](checkpoint/PARTS.md) |
185185
| [experience](experience/README.md) | [DIRECTION](experience/DIRECTION.md), [PARTS](experience/PARTS.md), [LANDING_LOG](experience/LANDING_LOG.md), [PROVENANCE](experience/PROVENANCE.md), [OWNER_REQUESTS](experience/OWNER_REQUESTS.md) |
186-
| [agon](agon/README.md) | [DIRECTION](agon/DIRECTION.md), [PARTS](agon/PARTS.md), [LANDING_LOG](agon/LANDING_LOG.md), [PROVENANCE](agon/PROVENANCE.md), [legacy index](agon/legacy/INDEX.md) |
186+
| [agon](agon/README.md) | [PARTS](agon/PARTS.md), [DIRECTION](agon/DIRECTION.md), [LANDING_LOG](agon/LANDING_LOG.md), [PROVENANCE](agon/PROVENANCE.md), [legacy index](agon/legacy/INDEX.md) |
187187
| [antifragility](antifragility/README.md) | [ANTIFRAGILITY](antifragility/docs/ANTIFRAGILITY.md), [VIA_NEGATIVA](antifragility/docs/VIA_NEGATIVA.md), [ANTI_AUTHORITY_RULES](antifragility/docs/ANTI_AUTHORITY_RULES.md), [ONE_IN_ONE_OUT](antifragility/docs/ONE_IN_ONE_OUT.md), [FRAGILITY_BLACKLIST](../FRAGILITY_BLACKLIST.md), [DELETION_CANDIDATES.json](../docs/audits/DELETION_CANDIDATES.json) |
188188
| [questbook](questbook/README.md) | [model-spine](questbook/parts/model-spine/README.md), [source-contract](questbook/parts/source-contract/README.md), [relation-shape](questbook/parts/relation-shape/README.md), [quests](../quests/) |
189189
| [rpg](rpg/README.md) | [source-boundary](rpg/parts/source-boundary/README.md), [vocabulary-overlay](rpg/parts/vocabulary-overlay/README.md), [quest-campaign](rpg/parts/quest-campaign/README.md), [USAGE](rpg/USAGE.md) |
190190
| [boundary-bridge](boundary-bridge/README.md) | [ToS Support](boundary-bridge/parts/tos-support/README.md), [COUNTERPART_BRIDGE](boundary-bridge/docs/COUNTERPART_BRIDGE.md), [WITNESS_COMPOST](boundary-bridge/docs/WITNESS_COMPOST.md) |
191191
| [release-support](release-support/README.md) | [PUBLIC_SUPPORT_POSTURE](release-support/docs/PUBLIC_SUPPORT_POSTURE.md), [DIRECTION_SURFACES](release-support/docs/DIRECTION_SURFACES.md), [FEDERATION_RELEASE_PROTOCOL](release-support/docs/FEDERATION_RELEASE_PROTOCOL.md), [RELEASING](release-support/docs/RELEASING.md) |
192192

193-
## Agon Quick Map
194-
195-
Agon has many active parts, so this atlas keeps a name index for route
196-
discovery only. Use [Agon PARTS](agon/PARTS.md) and part-local files for
197-
meaning.
198-
199-
| Part | Route |
200-
|---|---|
201-
| Imposition Readiness | [imposition-readiness](agon/parts/imposition-readiness/README.md) |
202-
| Lawful Move Grammar | [lawful-move-grammar](agon/parts/lawful-move-grammar/README.md) |
203-
| Owner Binding | [owner-binding](agon/parts/owner-binding/README.md) |
204-
| Gate Routing | [gate-routing](agon/parts/gate-routing/README.md) |
205-
| Trial Handoff | [trial-handoff](agon/parts/trial-handoff/README.md) |
206-
| Recurrence Adapter | [recurrence-adapter](agon/parts/recurrence-adapter/README.md) |
207-
| Packet Arena | [packet-arena](agon/parts/packet-arena/README.md) |
208-
| Duel Kernel | [duel-kernel](agon/parts/duel-kernel/README.md) |
209-
| Verdict Retention Rank | [verdict-retention-rank](agon/parts/verdict-retention-rank/README.md) |
210-
| Epistemic KAG | [epistemic-kag](agon/parts/epistemic-kag/README.md) |
211-
| Sophian Threshold | [sophian-threshold](agon/parts/sophian-threshold/README.md) |
212-
| Compatibility Bridges | [compatibility-bridges](agon/parts/compatibility-bridges/README.md) |
213-
214193
## Artifact Placement
215194

216195
Mechanics are not documentation-only packages. When a schema, example, seed

‎tests/test_docs_verify_routes.py‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -133,13 +133,15 @@ def test_agon_preparation_routes_stay_center_bounded(self) -> None:
133133
readme = read_text("README.md")
134134
docs_readme = read_text("docs/README.md")
135135
mechanics = read_text("mechanics/README.md")
136+
parts = read_text("mechanics/agon/PARTS.md")
136137
roadmap = read_text("ROADMAP.md")
137138
layers = read_text("docs/LAYERS.md")
138139
repo_roles = read_text("docs/REPO_ROLES.md")
139140
posture = read_text("mechanics/agon/legacy/raw/AGON_PREPARATION_POSTURE.md")
140141

141142
self.assertIn("mechanics/agon/README.md", readme)
142-
self.assertIn("Imposition Readiness", mechanics)
143+
self.assertNotIn("Agon Quick Map", mechanics)
144+
self.assertIn("Imposition Readiness", parts)
143145
self.assertIn("agon/PROVENANCE.md", mechanics)
144146
self.assertIn("agon/legacy/INDEX.md", mechanics)
145147
self.assertIn("PROVENANCE", docs_readme)
@@ -158,6 +160,7 @@ def test_agon_imposition_routes_stay_center_bounded(self) -> None:
158160
readme = read_text("README.md")
159161
docs_readme = read_text("docs/README.md")
160162
mechanics = read_text("mechanics/README.md")
163+
parts = read_text("mechanics/agon/PARTS.md")
161164
landing_log = read_text("mechanics/agon/LANDING_LOG.md")
162165
layers = read_text("docs/LAYERS.md")
163166
repo_roles = read_text("docs/REPO_ROLES.md")
@@ -168,7 +171,7 @@ def test_agon_imposition_routes_stay_center_bounded(self) -> None:
168171
readiness = read_text("mechanics/agon/parts/imposition-readiness/generated/agon_imposition_readiness.min.json")
169172

170173
self.assertIn("mechanics/agon/README.md", readme)
171-
self.assertIn("Imposition Readiness", mechanics)
174+
self.assertIn("Imposition Readiness", parts)
172175
self.assertIn("agon/PROVENANCE.md", mechanics)
173176
self.assertIn("agon/legacy/INDEX.md", mechanics)
174177
self.assertIn("PROVENANCE", docs_readme)
@@ -189,6 +192,7 @@ def test_agon_lawful_move_routes_stay_center_bounded(self) -> None:
189192
readme = read_text("README.md")
190193
docs_readme = read_text("docs/README.md")
191194
mechanics = read_text("mechanics/README.md")
195+
parts = read_text("mechanics/agon/PARTS.md")
192196
landing_log = read_text("mechanics/agon/LANDING_LOG.md")
193197
layers = read_text("docs/LAYERS.md")
194198
repo_roles = read_text("docs/REPO_ROLES.md")
@@ -197,7 +201,7 @@ def test_agon_lawful_move_routes_stay_center_bounded(self) -> None:
197201
registry = read_text("mechanics/agon/parts/lawful-move-grammar/generated/agon_lawful_move_registry.min.json")
198202

199203
self.assertIn("mechanics/agon/README.md", readme)
200-
self.assertIn("Lawful Move Grammar", mechanics)
204+
self.assertIn("Lawful Move Grammar", parts)
201205
self.assertIn("agon/PROVENANCE.md", mechanics)
202206
self.assertIn("agon/legacy/INDEX.md", mechanics)
203207
self.assertIn("PROVENANCE", docs_readme)
@@ -213,6 +217,7 @@ def test_agon_move_owner_binding_routes_stay_center_bounded(self) -> None:
213217
readme = read_text("README.md")
214218
docs_readme = read_text("docs/README.md")
215219
mechanics = read_text("mechanics/README.md")
220+
parts = read_text("mechanics/agon/PARTS.md")
216221
landing_log = read_text("mechanics/agon/LANDING_LOG.md")
217222
layers = read_text("docs/LAYERS.md")
218223
repo_roles = read_text("docs/REPO_ROLES.md")
@@ -221,7 +226,7 @@ def test_agon_move_owner_binding_routes_stay_center_bounded(self) -> None:
221226
registry = read_text("mechanics/agon/parts/owner-binding/generated/agon_move_owner_binding_registry.min.json")
222227

223228
self.assertIn("mechanics/agon/README.md", readme)
224-
self.assertIn("Owner Binding", mechanics)
229+
self.assertIn("Owner Binding", parts)
225230
self.assertIn("agon/PROVENANCE.md", mechanics)
226231
self.assertIn("agon/legacy/INDEX.md", mechanics)
227232
self.assertIn("PROVENANCE", docs_readme)
@@ -237,6 +242,7 @@ def test_agon_gate_routing_handoff_routes_stay_center_bounded(self) -> None:
237242
readme = read_text("README.md")
238243
docs_readme = read_text("docs/README.md")
239244
mechanics = read_text("mechanics/README.md")
245+
parts = read_text("mechanics/agon/PARTS.md")
240246
landing_log = read_text("mechanics/agon/LANDING_LOG.md")
241247
layers = read_text("docs/LAYERS.md")
242248
repo_roles = read_text("docs/REPO_ROLES.md")
@@ -246,7 +252,7 @@ def test_agon_gate_routing_handoff_routes_stay_center_bounded(self) -> None:
246252

247253
self.assertIn("mechanics/agon/README.md", readme)
248254
self.assertIn("mechanics/README.md", docs_readme)
249-
self.assertIn("Gate Routing", mechanics)
255+
self.assertIn("Gate Routing", parts)
250256
self.assertIn("agon/PROVENANCE.md", mechanics)
251257
self.assertIn("agon/legacy/INDEX.md", mechanics)
252258
self.assertIn("Agon gate routing handoff", landing_log)
@@ -261,6 +267,7 @@ def test_agon_trial_playbook_handoff_routes_stay_center_bounded(self) -> None:
261267
readme = read_text("README.md")
262268
docs_readme = read_text("docs/README.md")
263269
mechanics = read_text("mechanics/README.md")
270+
parts = read_text("mechanics/agon/PARTS.md")
264271
landing_log = read_text("mechanics/agon/LANDING_LOG.md")
265272
layers = read_text("docs/LAYERS.md")
266273
repo_roles = read_text("docs/REPO_ROLES.md")
@@ -271,7 +278,7 @@ def test_agon_trial_playbook_handoff_routes_stay_center_bounded(self) -> None:
271278

272279
self.assertIn("mechanics/agon/README.md", readme)
273280
self.assertIn("mechanics/README.md", docs_readme)
274-
self.assertIn("Trial Handoff", mechanics)
281+
self.assertIn("Trial Handoff", parts)
275282
self.assertIn("agon/PROVENANCE.md", mechanics)
276283
self.assertIn("agon/legacy/INDEX.md", mechanics)
277284
self.assertIn("Agon trial playbook handoff", landing_log)

‎tests/test_mechanic_artifact_topology.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@
1010

1111

1212
class MechanicArtifactTopologyTests(unittest.TestCase):
13+
def test_artifact_topology_keeps_alias_rule_inside_placement_law(self) -> None:
14+
topology = (REPO_ROOT / "mechanics" / "ARTIFACT_TOPOLOGY.md").read_text()
15+
self.assertNotIn("## No Root Aliases", topology)
16+
self.assertIn("do not add root or flat", topology)
17+
self.assertIn("Package-local `legacy/raw`, seed, and landing receipt districts are allowed", topology)
18+
self.assertIn("without becoming alternate active routes", topology)
19+
self.assertIn("Questbook is the one intentional root-store exception", topology)
20+
1321
def test_validator_accepts_current_topology(self) -> None:
1422
result = subprocess.run(
1523
[sys.executable, "scripts/validate_mechanic_artifact_topology.py"],

0 commit comments

Comments
 (0)