arkgate 4.8.1 → 4.8.3
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/CHANGELOG.md +25 -2
- package/README.md +41 -8
- package/bin/lib/analysis-engine.mjs +6 -6
- package/bin/lib/ark-order-facts.mjs +59 -0
- package/bin/lib/ark-order-sensors.mjs +31 -2
- package/bin/lib/arkrule-file-hints.mjs +6 -2
- package/bin/lib/arkrules-contract.mjs +1 -0
- package/bin/lib/arkrules-sensors.mjs +22 -2
- package/bin/lib/config-extras.mjs +2 -0
- package/bin/lib/diagnostic-catalog.mjs +2 -1
- package/bin/lib/remediation.mjs +9 -1
- package/bin/lib/resolved-candidate-facts.mjs +31 -0
- package/dist/{configTypes-BdCe_gvv.d.ts → configTypes-dNJ2C0yx.d.ts} +5 -0
- package/dist/{diagnosticCatalog-CSF4N3w8.d.ts → diagnosticCatalog-C5GgeyEE.d.ts} +97 -7
- package/dist/eslint/index.cjs +6 -6
- package/dist/eslint/index.d.ts +1 -1
- package/dist/eslint/index.js +6 -6
- package/dist/index.cjs +34 -34
- package/dist/index.d.ts +24 -7
- package/dist/index.js +34 -34
- package/dist/nestjs/index.cjs +5 -5
- package/dist/nestjs/index.d.ts +3 -3
- package/dist/nestjs/index.js +5 -5
- package/dist/runtime/index.cjs +15 -15
- package/dist/runtime/index.d.ts +6 -6
- package/dist/runtime/index.js +15 -15
- package/dist/{types-C9KApBzX.d.ts → types-DeK7SYGC.d.ts} +1 -1
- package/dist/{types-DCSlrRnV.d.ts → types-dK24fDZa.d.ts} +1 -1
- package/docs/README.md +4 -4
- package/docs/agent-guide.md +10 -9
- package/docs/configuration.md +12 -8
- package/docs/develop.md +23 -2
- package/docs/diagnostics.md +9 -0
- package/docs/enthusiast/README.md +6 -4
- package/docs/package-surface.md +6 -2
- package/docs/product-voice.md +15 -5
- package/docs/use.md +8 -5
- package/package.json +1 -1
- package/schemas/ark.arkrules.schema.json +1 -0
- package/schemas/ark.config.schema.json +9 -0
- package/schemas/ark.resolved-candidate-facts.schema.json +1 -1
- package/server.json +2 -2
- package/templates/agent-skills/README.md +1 -1
- package/templates/agent-skills/ark-adopt/SKILL.md +46 -13
- package/templates/agent-skills/ark-architect/SKILL.md +4 -4
- package/templates/agent-skills/ark-autopilot/SKILL.md +22 -4
- package/templates/agent-skills/ark-contract/SKILL.md +11 -7
- package/templates/agent-skills/ark-coverage/SKILL.md +11 -5
- package/templates/agent-skills/ark-explain/SKILL.md +10 -4
- package/templates/agent-skills/ark-explore/SKILL.md +12 -4
- package/templates/agent-skills/ark-fix/SKILL.md +3 -3
- package/templates/agent-skills/ark-loop/SKILL.md +3 -3
- package/templates/agent-skills/ark-place/SKILL.md +17 -4
- package/templates/agent-skills/ark-runtime/SKILL.md +13 -11
- package/templates/agent-skills/ark-think/SKILL.md +13 -7
- package/templates/agent-skills/ark-upgrade/SKILL.md +12 -4
- package/templates/arkrules/ApplicationOrchestration.json +6 -0
- package/templates/skills/ark-adopt.md +46 -13
- package/templates/skills/ark-architect.md +4 -4
- package/templates/skills/ark-autopilot.md +22 -4
- package/templates/skills/ark-contract.md +11 -7
- package/templates/skills/ark-coverage.md +11 -5
- package/templates/skills/ark-explain.md +10 -4
- package/templates/skills/ark-explore.md +12 -4
- package/templates/skills/ark-fix.md +3 -3
- package/templates/skills/ark-loop.md +3 -3
- package/templates/skills/ark-place.md +17 -4
- package/templates/skills/ark-runtime.md +13 -11
- package/templates/skills/ark-think.md +13 -7
- package/templates/skills/ark-upgrade.md +12 -4
|
@@ -20,8 +20,9 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
|
|
|
20
20
|
- Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
|
|
21
21
|
- Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
|
|
22
22
|
- CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
|
|
23
|
-
- Do not add `arkRun` unless the user wants
|
|
24
|
-
|
|
23
|
+
- Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
|
|
24
|
+
**advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
|
|
25
|
+
Absence is silent and valid. Compact starter stays extras-off. Skills never enforce.
|
|
25
26
|
|
|
26
27
|
Invoking this skill **is** the approval. Write the architecture config in this turn.
|
|
27
28
|
Greenfield: scaffold like `--recommend`. Brownfield: match **product
|
|
@@ -96,7 +97,8 @@ When present, prefer the consumer **domain glossary** for layer names, slice fol
|
|
|
96
97
|
| False-green / concentrated edge needs config truth | Feature file only → `/ark-place` |
|
|
97
98
|
| Mine loose business rules into Domain / advisory ArkRules | Apply leftover design after the path is honest → `/ark-autopilot` |
|
|
98
99
|
| Freeze **real** debt after the config is honest | User said map only |
|
|
99
|
-
| Turn **advisory** ArkRun on (`arkRun` extra, schema `1.2
|
|
100
|
+
| Turn **advisory** ArkRun on (`arkRun` extra, schema `1.2+`; **`kernelRoots` preferred**) | Evaluate / wire a hand-rolled bus → `/ark-runtime`; new kernel-managed file → `/ark-place` |
|
|
101
|
+
| Turn **advisory** ArkOrder on (`arkOrder` extra, schema `1.3+`, `planeRoots`) | New plane-root file after extra is on → `/ark-place`; grind skip clusters → `/ark-autopilot` |
|
|
100
102
|
|
|
101
103
|
## Dual engine (mandatory)
|
|
102
104
|
|
|
@@ -116,33 +118,36 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
116
118
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
117
119
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
118
120
|
|
|
119
|
-
## Dual plane — layers +
|
|
121
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
120
122
|
|
|
121
|
-
ArkGate has **
|
|
123
|
+
ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
|
|
122
124
|
|
|
123
125
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
124
126
|
|-------|------------------|----------------|-----------------|
|
|
125
127
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
126
128
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
127
|
-
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime` | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
129
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
130
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
128
131
|
|
|
129
132
|
**Rules for every report / answer:**
|
|
130
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** (or a
|
|
133
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
131
134
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
132
135
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
133
136
|
4. Editing `arkrules/*` or promoting modes is **this skill** (session 0) or **`/ark-autopilot`** later; never invent `mechanical-safe`.
|
|
134
137
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
135
138
|
6. Absence of `arkRun` is **valid**. Write it only when the user wants the extra. Skills never enforce.
|
|
139
|
+
7. Absence of `arkOrder` is **valid**. Write it only when the user wants the extra. Do not invent `/ark-order`. Skills never enforce.
|
|
136
140
|
|
|
137
141
|
|
|
138
142
|
### Adopt + ArkRules
|
|
139
143
|
- After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
|
|
140
144
|
- Mine rules → inventory + write advisory invariants/structure into `arkrules/<Layer>.json` **in this turn**.
|
|
145
|
+
- Application / Features templates include advisory `writes-via-aggregate`: driver import + write token in a use case is the skip. Do not copy `Externals/` / `admission.ts` folder religion.
|
|
141
146
|
- Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
|
|
142
147
|
|
|
143
148
|
### Adopt + ArkRun
|
|
144
149
|
- User asked to turn the extra on: write **advisory** `arkRun` on `ark.config.json` (`schemaVersion` `1.2+`) **in this turn**. Default `"mode": "advisory"`.
|
|
145
|
-
- Required shape: `
|
|
150
|
+
- Required shape: **`kernelRoots` preferred** (real files; empty + enforced fails closed). `compositionRoots` is a legacy alias — still valid. `managedLayers` (existing `layers[].name` only), `requireDeclarations` (default true).
|
|
146
151
|
- Do **not** put `arkRun` on the compact starter / `ark start` scaffold. Brownfield stays advisory until the team promotes.
|
|
147
152
|
- Absence is valid and **silent** — never force the extra. Never force the kernel over existing Nest/DI. Do not invent `/ark-run`.
|
|
148
153
|
- Import from `arkgate/runtime` (factory `createStrictArkKernel`, per instance, no process-wide singleton). `@arkgate/runtime` is deprecated. No shipped cloud broker SDKs.
|
|
@@ -150,6 +155,32 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
150
155
|
- Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
|
|
151
156
|
- After the extra is honest: handoff `/ark-runtime` to wire one candidate, `/ark-place` for new kernel-managed files. Skills never enforce.
|
|
152
157
|
|
|
158
|
+
### Adopt + ArkOrder
|
|
159
|
+
- User asked to turn the extra on: write **advisory** `arkOrder` on `ark.config.json` (`schemaVersion` `1.3+`) **in this turn**. Default `"mode": "advisory"` — never session-0 default `enforced`.
|
|
160
|
+
- Required shape: `planeRoots` (real files; empty + enforced = `ARKORDER_MISSING_PLANE`), `managedLayers` (existing `layers[].name` only), `maxXiKeys` (default 7), **`xiKeys`** (the 3–5 slow names; empty = field-write sensor silent).
|
|
161
|
+
- Example (consumer trees — not this library's 4-layer compact). Copy billing, **rename the three keys**:
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"schemaVersion": "1.3",
|
|
166
|
+
"arkOrder": {
|
|
167
|
+
"mode": "advisory",
|
|
168
|
+
"planeRoots": ["src/main.ts"],
|
|
169
|
+
"managedLayers": ["Application"],
|
|
170
|
+
"maxXiKeys": 7,
|
|
171
|
+
"xiKeys": ["plan", "cycle", "tenancy"]
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- `xiKeys` are meaning, not membership. `projectId` / `orgId` do not belong. If `proposeRelease` throws empty blast, that key does not order anything.
|
|
177
|
+
- A use-case that `prisma.*.update({ plan })` while `plan` is in `xiKeys` is **[ArkOrder]** `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
|
|
178
|
+
|
|
179
|
+
- Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).
|
|
180
|
+
- Absence is valid and **silent** — never force the extra. Do not invent `/ark-order`.
|
|
181
|
+
- Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
|
|
182
|
+
- After the extra is honest: handoff `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
|
|
183
|
+
|
|
153
184
|
## Subagent fan-out (optional, host-dependent)
|
|
154
185
|
|
|
155
186
|
When the user asks to go faster **or** the work naturally splits (multiple packages,
|
|
@@ -200,8 +231,10 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
|
|
|
200
231
|
**Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
|
|
201
232
|
**ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
|
|
202
233
|
User wants the ArkRun extra → write **advisory** `arkRun` (schema `1.2+`, real
|
|
203
|
-
`compositionRoots
|
|
204
|
-
|
|
234
|
+
`kernelRoots` preferred — `compositionRoots` alias, existing `managedLayers`) **in this turn**.
|
|
235
|
+
User wants the ArkOrder extra → write **advisory** `arkOrder` (schema `1.3+`, real
|
|
236
|
+
`planeRoots`, existing `managedLayers`, `maxXiKeys` 7) **in this turn**. Do not add extras
|
|
237
|
+
to a compact starter. Do not promote to enforced as the session-0 default.
|
|
205
238
|
2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
|
|
206
239
|
Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
|
|
207
240
|
If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
|
|
@@ -244,9 +277,9 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
|
|
|
244
277
|
|
|
245
278
|
- Freeze false positives to get green.
|
|
246
279
|
- Force runtime kernel over existing Nest/DI.
|
|
247
|
-
- Put `arkRun` on the compact starter / `ark start` scaffold.
|
|
280
|
+
- Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
|
|
248
281
|
- Claim in-memory kernel stores are production durability.
|
|
249
|
-
- Invent `/ark-run`.
|
|
282
|
+
- Invent `/ark-run` or `/ark-order`.
|
|
250
283
|
- Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
|
|
251
284
|
- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
|
|
252
285
|
|
|
@@ -258,7 +291,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
258
291
|
- **Sensor:** commands/tools run
|
|
259
292
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
260
293
|
- **Result:** one-line outcome
|
|
261
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** (or `n/a` if unused)
|
|
294
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
262
295
|
- **Compass:** top residual lenses | `n/a`
|
|
263
296
|
- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
|
|
264
297
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
@@ -40,9 +40,9 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
|
|
|
40
40
|
|
|
41
41
|
Then call **`ark_recommend`** with the same bound `project` envelope (or `ark-check --recommend`).
|
|
42
42
|
|
|
43
|
-
## Dual plane — layers +
|
|
43
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
44
44
|
|
|
45
|
-
Label findings **`[Layer]`** vs **`[ArkRules]`**. Absence of
|
|
45
|
+
Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. Session-0 extras (advisory `arkRun` / advisory `arkOrder`) live on **`/ark-adopt`**. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
|
|
46
46
|
|
|
47
47
|
## Subagent fan-out (optional, host-dependent)
|
|
48
48
|
|
|
@@ -57,7 +57,7 @@ If the host supports **parallel subagents**, fan out read-only scouts; otherwise
|
|
|
57
57
|
## Steps
|
|
58
58
|
|
|
59
59
|
1. Bind MCP (`ark_identity` then `ark_recommend`) or run `ark-check --recommend`.
|
|
60
|
-
2. Execute **`/ark-adopt`** autonomy: write the config, dirs, optional advisory ArkRules, gates.
|
|
60
|
+
2. Execute **`/ark-adopt`** autonomy: write the config, dirs, optional advisory ArkRules, optional advisory ArkRun / ArkOrder when asked, gates.
|
|
61
61
|
3. `ark-check --strict-config`. Handoff `/ark-place` for new files.
|
|
62
62
|
|
|
63
63
|
## Completion contract (skill incomplete if missing)
|
|
@@ -68,7 +68,7 @@ Skill incomplete if missing any field below.
|
|
|
68
68
|
- **Sensor:** commands/tools run
|
|
69
69
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
70
70
|
- **Result:** one-line outcome
|
|
71
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
71
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
72
72
|
- **Compass:** top residual lenses | `n/a`
|
|
73
73
|
- **Handoff:** `/ark-adopt` / `/ark-place` / `none`
|
|
74
74
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -60,6 +60,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
|
|
|
60
60
|
| Brownfield or greenfield with apply | Session 0 / config lying → `/ark-adopt` first, then return |
|
|
61
61
|
| User wants A + B planned and **applied** | New file only → `/ark-place` |
|
|
62
62
|
| **Apply** leftover design (one Shape refactor) | User said map only |
|
|
63
|
+
| Extra skip cluster (`ARKRUN_*` / `ARKORDER_*`) after extra is on | Extra off → `/ark-adopt` (advisory); evaluate one bus → `/ark-runtime` |
|
|
63
64
|
| Spaghetti under ENFORCE: Shape work (invoke = apply one pilot) | — |
|
|
64
65
|
|
|
65
66
|
**Post-green door:** `/ark-explore` shape-focus → dual-plan B, **then this skill applies one
|
|
@@ -110,21 +111,24 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
110
111
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
111
112
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
112
113
|
|
|
113
|
-
## Dual plane — layers +
|
|
114
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
114
115
|
|
|
115
|
-
ArkGate has **
|
|
116
|
+
ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
|
|
116
117
|
|
|
117
118
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
118
119
|
|-------|------------------|----------------|-----------------|
|
|
119
120
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
120
121
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
122
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
123
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
121
124
|
|
|
122
125
|
**Rules for every report / answer:**
|
|
123
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
126
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
124
127
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
125
128
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
126
129
|
4. Editing `arkrules/*` or promoting modes and fixing structure sensors is **this skill** (judgment, never invent `mechanical-safe`).
|
|
127
130
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
131
|
+
6. Absence of extras is **valid**. Extra skip clusters grind **here** after the extra is on. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
|
|
128
132
|
|
|
129
133
|
|
|
130
134
|
### Autopilot + ArkRules
|
|
@@ -134,6 +138,19 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
134
138
|
- Never promote advisory→enforced without coverage evidence (`canPromoteInvariant` / policy-delta).
|
|
135
139
|
- End report must list what was **layer-edge** work vs **intra-layer rule** work.
|
|
136
140
|
|
|
141
|
+
### Autopilot + ArkRun
|
|
142
|
+
When `arkRun` is present:
|
|
143
|
+
- Grind skip clusters with judgment: `ARKRUN_DIRECT_NEW` / `ARKRUN_TRANSPORT_BYPASS` / `ARKRUN_KERNEL_IN_DOMAIN` / `ARKRUN_MISSING_ROOT`. Never invent `mechanical-safe` for new emits / homemade buses.
|
|
144
|
+
- Factory only inside `arkRun.kernelRoots` (`compositionRoots` alias). Import `arkgate/runtime`. Doctor `arkRun` is `notAScore`.
|
|
145
|
+
- Extra off → `/ark-adopt` (advisory) or `/ark-runtime` (evaluate one candidate). Do not invent `/ark-run`.
|
|
146
|
+
- Skills never enforce.
|
|
147
|
+
|
|
148
|
+
### Autopilot + ArkOrder
|
|
149
|
+
When `arkOrder` is present:
|
|
150
|
+
- Grind skip clusters with judgment: `ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`. Freeze ξ with `release()`; never `update`/`patch`/`set`. Name `xiKeys`; do not persist those keys from a use-case.
|
|
151
|
+
- Extra off → `/ark-adopt` (advisory). Do not invent `/ark-order`.
|
|
152
|
+
- Skills never enforce.
|
|
153
|
+
|
|
137
154
|
## Subagent fan-out (optional, host-dependent)
|
|
138
155
|
|
|
139
156
|
When the user asks to go faster **or** the work naturally splits (multiple packages,
|
|
@@ -249,6 +266,7 @@ Status lights from doctor — not settings you choose. Rank residual honestly:
|
|
|
249
266
|
- Claim ENFORCE / “done” when doctor reports `contract-false-green-io-under-application` (adopt first).
|
|
250
267
|
- Claim “done” solely because plan A is empty while explore/B residual remains unlisted.
|
|
251
268
|
- Replace host Nest/DI with the runtime kernel unasked.
|
|
269
|
+
- Invent `/ark-run` or `/ark-order`.
|
|
252
270
|
- Auto-apply pattern (B) bets as if they were mechanical-safe.
|
|
253
271
|
- Create origin only after a long cleanup (freezes a polished “before” that never was).
|
|
254
272
|
|
|
@@ -270,7 +288,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
270
288
|
- **Sensor:** commands/tools run
|
|
271
289
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
272
290
|
- **Result:** one-line outcome
|
|
273
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
291
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
274
292
|
- **Compass:** top residual lenses | `n/a`
|
|
275
293
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
276
294
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -17,7 +17,7 @@ preview-only. Never weaken the architecture config.
|
|
|
17
17
|
|
|
18
18
|
| Use this leftover name when… | Prefer instead |
|
|
19
19
|
|------------------------------|----------------|
|
|
20
|
-
| Layers / include / ArkRules / **ArkRun extra** need an edit | **`/ark-adopt`** (path, first `arkRun`) or **`/ark-autopilot`** (tighten) |
|
|
20
|
+
| Layers / include / ArkRules / **ArkRun extra** / **ArkOrder extra** need an edit | **`/ark-adopt`** (path, first `arkRun` / first `arkOrder`) or **`/ark-autopilot`** (tighten) |
|
|
21
21
|
| False-green / concentrated edge | **`/ark-adopt`** — write the honest config |
|
|
22
22
|
| Kernel extra / one kernel candidate | **`/ark-runtime`** — leftover name; wires `arkgate/runtime`, not a second package |
|
|
23
23
|
|
|
@@ -39,9 +39,13 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
39
39
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
40
40
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
41
41
|
|
|
42
|
-
## Dual plane — layers +
|
|
42
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
43
43
|
|
|
44
|
-
Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`**. Absence of
|
|
44
|
+
Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. First-time extra is **`/ark-adopt`** (advisory). Wire one kernel candidate with **`/ark-runtime`**. New kernel-managed / plane-root file with **`/ark-place`**. Grind skip clusters with **`/ark-autopilot`**. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
|
|
45
|
+
|
|
46
|
+
Application / Features may declare advisory **`writes-via-aggregate`**: a use-case that imports a persistence driver and calls `.insert` / `.create` / `INSERT INTO` is the skip. Persistence adapters stay the write edge. Do not add `Externals/` or `admission.ts` as contract law.
|
|
47
|
+
|
|
48
|
+
When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids are not keys. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. Copy [examples/arkorder-billing/](../../../examples/arkorder-billing/) and rename the three keys.
|
|
45
49
|
|
|
46
50
|
## Subagent fan-out (optional, host-dependent)
|
|
47
51
|
|
|
@@ -55,9 +59,9 @@ If the host supports **parallel subagents**, fan out read-only scouts; otherwise
|
|
|
55
59
|
|
|
56
60
|
## Steps
|
|
57
61
|
|
|
58
|
-
1. If the path is missing or lying → execute **`/ark-adopt`** (including first advisory `arkRun`).
|
|
59
|
-
2. If the path is honest and you are tightening rules or
|
|
60
|
-
3.
|
|
62
|
+
1. If the path is missing or lying → execute **`/ark-adopt`** (including first advisory `arkRun` / first advisory `arkOrder`).
|
|
63
|
+
2. If the path is honest and you are tightening rules or extras (`arkRun` / `arkOrder`) → execute **`/ark-autopilot`**.
|
|
64
|
+
3. One kernel candidate (extra already on) → **`/ark-runtime`**. `ark-check --strict-config`.
|
|
61
65
|
|
|
62
66
|
## Completion contract (skill incomplete if missing)
|
|
63
67
|
|
|
@@ -67,7 +71,7 @@ Skill incomplete if missing any field below.
|
|
|
67
71
|
- **Sensor:** commands/tools run
|
|
68
72
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
69
73
|
- **Result:** one-line outcome
|
|
70
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** (or `n/a` if unused)
|
|
74
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
71
75
|
- **Compass:** top residual lenses | `n/a`
|
|
72
76
|
- **Handoff:** `/ark-adopt` / `/ark-autopilot` / `none`
|
|
73
77
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -75,27 +75,33 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
75
75
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
76
76
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
77
77
|
|
|
78
|
-
## Dual plane — layers +
|
|
78
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
79
79
|
|
|
80
|
-
ArkGate has **
|
|
80
|
+
ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
|
|
81
81
|
|
|
82
82
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
83
83
|
|-------|------------------|----------------|-----------------|
|
|
84
84
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
85
85
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
86
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
87
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
86
88
|
|
|
87
89
|
**Rules for every report / answer:**
|
|
88
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
90
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
89
91
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
90
92
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
91
|
-
4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
|
|
93
|
+
4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`** / leftover **`/ark-contract`**; fixing code under a structure sensor is leftover **`/ark-fix`** / **`/ark-loop`** or **`/ark-autopilot`** (judgment, never invent mechanical-safe).
|
|
92
94
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
95
|
+
6. Extras silent when off. Doctor `arkRun` is `notAScore`. Do not force extras. Do not invent `/ark-run` or `/ark-order`.
|
|
93
96
|
|
|
94
97
|
|
|
95
98
|
### Coverage + ArkRules
|
|
96
99
|
- Fitness report: governed% / gates / baseline = **[Layer]**; `rulesUnderContract` inventoried/under-contract/frozen = **[ArkRules]** (counts, never a score).
|
|
97
100
|
- Capability gap: “no arkRules map” is optional adoption opportunity, not a failed gate.
|
|
98
101
|
|
|
102
|
+
### Coverage + extras
|
|
103
|
+
- Extras silent when off. Doctor `arkRun` is `notAScore`. “No arkRun / arkOrder” is not a failed gate. Do not force extras.
|
|
104
|
+
|
|
99
105
|
## Subagent fan-out (optional, host-dependent)
|
|
100
106
|
|
|
101
107
|
When the user asks to go faster **or** the work naturally splits (multiple packages,
|
|
@@ -183,7 +189,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
183
189
|
- **Sensor:** commands/tools run
|
|
184
190
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
185
191
|
- **Result:** one-line outcome
|
|
186
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
192
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
187
193
|
- **Compass:** top residual lenses | `n/a`
|
|
188
194
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
189
195
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -59,21 +59,24 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
59
59
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
60
60
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
61
61
|
|
|
62
|
-
## Dual plane — layers +
|
|
62
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
63
63
|
|
|
64
|
-
ArkGate has **
|
|
64
|
+
ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
|
|
65
65
|
|
|
66
66
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
67
67
|
|-------|------------------|----------------|-----------------|
|
|
68
68
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
69
69
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
70
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
71
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
70
72
|
|
|
71
73
|
**Rules for every report / answer:**
|
|
72
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
74
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
73
75
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
74
76
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
75
77
|
4. Editing `arkrules/*` or applying structure fixes is **`/ark-adopt`** / **`/ark-autopilot`** (never invent `mechanical-safe`).
|
|
76
78
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
79
|
+
6. Extras silent when off. Doctor `arkRun` is `notAScore`. Do not force extras. Do not invent `/ark-run` or `/ark-order`.
|
|
77
80
|
|
|
78
81
|
|
|
79
82
|
### Explain + ArkRules
|
|
@@ -92,6 +95,9 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
92
95
|
- Green edges + covered catalog ≠ elegant Shape (design-weak residual stays honest).
|
|
93
96
|
- Never merge Layers and ArkRules into one “architecture score.”
|
|
94
97
|
|
|
98
|
+
### Explain + extras
|
|
99
|
+
- Extras silent when off. If `arkRun` is on, doctor `arkRun` is `notAScore` — never a tour score. Do not force extras.
|
|
100
|
+
|
|
95
101
|
## Subagent fan-out (optional, host-dependent)
|
|
96
102
|
|
|
97
103
|
If the host supports **parallel subagents** and the task splits cleanly (e.g. multiple
|
|
@@ -222,7 +228,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
222
228
|
- **Sensor:** commands/tools run (include report + browser-open command when used)
|
|
223
229
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
224
230
|
- **Result:** one-line outcome (include `ark-report.html` path; note if browser open was attempted)
|
|
225
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
231
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
226
232
|
- **Compass:** top residual lenses | `n/a`
|
|
227
233
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
228
234
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -139,21 +139,24 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
139
139
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
140
140
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
141
141
|
|
|
142
|
-
## Dual plane — layers +
|
|
142
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
143
143
|
|
|
144
|
-
ArkGate has **
|
|
144
|
+
ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; you **always label** findings so they never blur. Absence of an extra is silent and valid. Skills never enforce. ArkOrder is an extra **inside** the `arkgate` package (`arkgate/order`), not a second install.
|
|
145
145
|
|
|
146
146
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
147
147
|
|-------|------------------|----------------|-----------------|
|
|
148
148
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
149
149
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
150
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
151
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
150
152
|
|
|
151
153
|
**Rules for every report / answer:**
|
|
152
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
154
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
153
155
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
154
156
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
155
157
|
4. Editing `arkrules/*` or applying structure fixes is **`/ark-adopt`** / **`/ark-autopilot`** — explore does not write (never invent `mechanical-safe`).
|
|
156
158
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
159
|
+
6. Never write `arkRun` or `arkOrder` from this skill. When extras are present, label residual **`[ArkRun]`** / **`[ArkOrder]`**. Do not invent `/ark-run` or `/ark-order`.
|
|
157
160
|
|
|
158
161
|
|
|
159
162
|
### Explore + ArkRules
|
|
@@ -162,6 +165,10 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
162
165
|
- Dual-plan **B** may include: place advisory structure rules, extract one inventory candidate to Domain + `arkrules` entry, promote one covered invariant.
|
|
163
166
|
- Field path: note whether starters emit `arkrules/*`.
|
|
164
167
|
|
|
168
|
+
### Explore + extras
|
|
169
|
+
- Map extras when present; never write `arkRun` / `arkOrder`. Extra off → residual `n/a` / silent.
|
|
170
|
+
- Field path may name `examples/arkorder-billing/` (ArkOrder fixture — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
|
|
171
|
+
|
|
165
172
|
## Output mode (pick one — do not invent a fourth)
|
|
166
173
|
|
|
167
174
|
| Mode | When | Deliverable |
|
|
@@ -289,6 +296,7 @@ When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim
|
|
|
289
296
|
3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
|
|
290
297
|
4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
|
|
291
298
|
5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
|
|
299
|
+
6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name `examples/arkorder-billing/`. Never write extras from this skill.
|
|
292
300
|
|
|
293
301
|
If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
|
|
294
302
|
- Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or
|
|
@@ -431,7 +439,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
431
439
|
- **Sensor:** commands/tools run
|
|
432
440
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
433
441
|
- **Result:** one-line outcome
|
|
434
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
442
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
435
443
|
- **Compass:** top residual lenses | `n/a`
|
|
436
444
|
- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
|
|
437
445
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
@@ -46,9 +46,9 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
46
46
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
47
47
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
48
48
|
|
|
49
|
-
## Dual plane — layers +
|
|
49
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
50
50
|
|
|
51
|
-
Label findings **`[Layer]`** vs **`[ArkRules]`**.
|
|
51
|
+
Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. Extra skip clusters (`ARKRUN_*` / `ARKORDER_*`) are **`/ark-autopilot`**. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
|
|
52
52
|
|
|
53
53
|
## Subagent fan-out (optional, host-dependent)
|
|
54
54
|
|
|
@@ -83,7 +83,7 @@ Skill incomplete if missing any field below.
|
|
|
83
83
|
- **Sensor:** commands/tools run
|
|
84
84
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
85
85
|
- **Result:** one-line outcome
|
|
86
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
86
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
87
87
|
- **Compass:** top residual lenses | `n/a`
|
|
88
88
|
- **Handoff:** `/ark-autopilot` / `/ark-adopt` / `none`
|
|
89
89
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -41,9 +41,9 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
|
|
|
41
41
|
|
|
42
42
|
Atomic multi-file work uses **`ark_prepare_change`** with the same matched `project` envelope.
|
|
43
43
|
|
|
44
|
-
## Dual plane — layers +
|
|
44
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
45
45
|
|
|
46
|
-
Label findings **`[Layer]`** vs **`[ArkRules]`**. Never invent `mechanical-safe` kinds.
|
|
46
|
+
Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrder]`**. Absence of extras is valid and silent. Extra skip clusters (`ARKRUN_*` / `ARKORDER_*`) are **`/ark-autopilot`**. Never invent `mechanical-safe` kinds. Do not invent `/ark-run` or `/ark-order`. Skills never enforce.
|
|
47
47
|
|
|
48
48
|
## Subagent fan-out (optional, host-dependent)
|
|
49
49
|
|
|
@@ -79,7 +79,7 @@ Skill incomplete if missing any field below.
|
|
|
79
79
|
- **Sensor:** commands/tools run
|
|
80
80
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
81
81
|
- **Result:** one-line outcome
|
|
82
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
82
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
83
83
|
- **Compass:** top residual lenses | `n/a`
|
|
84
84
|
- **Handoff:** `/ark-autopilot` / `/ark-explore` / `none`
|
|
85
85
|
- **Incomplete?** `no` | `yes — <what is missing>`
|
|
@@ -20,8 +20,12 @@ description: "Where does new code go? Names the folder from the rules file and w
|
|
|
20
20
|
- Golden pattern is load-bearing when present. Adopt generates it.
|
|
21
21
|
- Do not default a repository to Presentation.
|
|
22
22
|
- When `arkRun` is on: scaffold through the kernel (no `new` of managed types; declare
|
|
23
|
-
`uses` / `reactsTo` / `raises` / `sends
|
|
23
|
+
`uses` / `reactsTo` / `raises` / `sends`; factory only in `arkRun.kernelRoots`,
|
|
24
|
+
`compositionRoots` alias). Extra off → do not introduce the kernel. Enable it
|
|
24
25
|
via `/ark-adopt`. Skills never enforce.
|
|
26
|
+
- When `arkOrder` is on: factory only in `arkOrder.planeRoots`; Domain stays plane-free;
|
|
27
|
+
freeze ξ with `release()`. Extra off → do not introduce the plane. Enable it via
|
|
28
|
+
`/ark-adopt`. Skills never enforce.
|
|
25
29
|
|
|
26
30
|
## Autonomy contract
|
|
27
31
|
|
|
@@ -66,6 +70,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
|
|
|
66
70
|
| New artifact: where + **write** under the config | Existing violation cluster → `/ark-autopilot` |
|
|
67
71
|
| Naming / directory for a known kind | Session 0 / config missing or lying → `/ark-adopt` (then come back) |
|
|
68
72
|
| Kernel-managed artifact when `arkRun` is already on | Extra not chosen yet → `/ark-adopt` (advisory `arkRun`); evaluate / migrate a hand-rolled bus → `/ark-runtime` |
|
|
73
|
+
| Plane-root artifact when `arkOrder` is already on | Extra not chosen yet → `/ark-adopt` (advisory `arkOrder`); skip cluster grind → `/ark-autopilot` |
|
|
69
74
|
|
|
70
75
|
The user describes something they need to build (a saga, a background job, an
|
|
71
76
|
event handler, a repository, an HTTP client, a use case, a projection, …).
|
|
@@ -108,7 +113,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
|
|
|
108
113
|
|-------|------------------|----------------|-----------------|
|
|
109
114
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
110
115
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
111
|
-
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime` | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
116
|
+
| **ArkRun** (extra) | Kernel usage + complete declarations | `arkRun` on `ark.config.json` (schema `1.2+`); factory `arkgate/runtime`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
112
117
|
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
113
118
|
|
|
114
119
|
**Rules for every report / answer:**
|
|
@@ -122,13 +127,14 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
|
|
|
122
127
|
|
|
123
128
|
|
|
124
129
|
### Place + ArkRules
|
|
125
|
-
- Choose layer from contract **and** check structure sensors for that layer (private state, factory, thin adapter).
|
|
130
|
+
- Choose layer from contract **and** check structure sensors for that layer (private state, factory, thin adapter, writes-via-aggregate).
|
|
126
131
|
- Scaffold to satisfy **[ArkRules]** when present; state which sensors apply.
|
|
132
|
+
- Persistence **writes** (insert/update/delete against a driver) go through a Domain aggregate + persistence adapter. Application/Feature files that import Prisma/pg/Supabase and call `.insert` / `.create` are **[ArkRules]** `writes-via-aggregate`. Do not invent `Externals/` or `admission.ts`.
|
|
127
133
|
|
|
128
134
|
### Place + ArkRun
|
|
129
135
|
When `arkRun` is present on the architecture config:
|
|
130
136
|
- Scaffold kernel-managed artifacts **through the kernel**, not `new` of an admitted type (`ARKRUN_DIRECT_NEW`).
|
|
131
|
-
- Call `createStrictArkKernel` (or an admission sibling) only inside `arkRun.compositionRoots
|
|
137
|
+
- Call `createStrictArkKernel` (or an admission sibling) only inside `arkRun.kernelRoots` (`compositionRoots` is a legacy alias — still valid). Each call is a new instance — no process-wide `getKernel()`.
|
|
132
138
|
- Domain-role files stay kernel-free (`ARKRUN_KERNEL_IN_DOMAIN`). Import from `arkgate/runtime` (or `arkgate/nestjs`). `@arkgate/runtime` is deprecated.
|
|
133
139
|
- List `uses` / `reactsTo` / `raises` / `sends` when `requireDeclarations` is on. Adding an existing call-site literal to the declaration list is the only mechanical-safe ArkRun edit; inventing a new emit / handle / depend is judgment.
|
|
134
140
|
- Do not import a homemade bus (`EventEmitter`, queue clients) in `managedLayers` — send on the kernel transport (`local` / `localBlocking` / `broker`; `ephemeral` defaults true). No shipped cloud SDKs.
|
|
@@ -141,6 +147,8 @@ When `arkOrder` is present on the architecture config:
|
|
|
141
147
|
- Import `createOrderPlane` from `arkgate/order` (same npm package). Domain-role files stay plane-free.
|
|
142
148
|
- Freeze ξ with `release()`; derive s with `project()`; field `ingest()` never mints a pattern; `proposeRelease()` needs a non-empty blast. There is no `update`/`patch`/`set`.
|
|
143
149
|
- Call the factory only inside `arkOrder.planeRoots`. Empty roots in `enforced` mode is `ARKORDER_MISSING_PLANE`.
|
|
150
|
+
- Named slow keys live in `arkOrder.xiKeys`. A managed-layer Prisma/pg write of those keys is `ARKORDER_XI_FIELD_WRITE` — absorb with `ingest` or change the pattern with `proposeRelease`.
|
|
151
|
+
- Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`): place this artifact, then grind via `/ark-autopilot`. Extra not on → `/ark-adopt`. Do not invent `/ark-order`.
|
|
144
152
|
- Absence of the extra is valid. Do not invent `/ark-order`. Skills never enforce.
|
|
145
153
|
|
|
146
154
|
## Subagent fan-out (optional, host-dependent)
|
|
@@ -172,6 +180,8 @@ the same files or weaken the gate.
|
|
|
172
180
|
- Orchestrates a use case, no I/O of its own → application layer.
|
|
173
181
|
- Talks to a database, queue, API, filesystem → an adapter layer on the side
|
|
174
182
|
that matches the direction (driven/persistence vs driving/http).
|
|
183
|
+
**Writes** go through a Domain aggregate that uses a persistence port; the
|
|
184
|
+
adapter implements the port. Do not put `prisma.order.create` in a use case.
|
|
175
185
|
- Reacts to events, long-running coordination (saga/workflow), scheduled
|
|
176
186
|
jobs, projections → the event/workflow layers if the config declares them.
|
|
177
187
|
When `arkRun` is on, wire those through the kernel (register + declarations),
|
|
@@ -208,6 +218,9 @@ the same files or weaken the gate.
|
|
|
208
218
|
- If `arkRun` is on and the user is grinding skip violations (`new` of managed types, homemade
|
|
209
219
|
bus) across many files: place this artifact through the kernel, then leftover `/ark-fix` /
|
|
210
220
|
`/ark-autopilot`. Extra not on → `/ark-adopt` (advisory) or `/ark-runtime` (evaluate).
|
|
221
|
+
- If `arkOrder` is on and the user is grinding skip violations (`ARKORDER_*`) across many files:
|
|
222
|
+
place this artifact on a plane root, then leftover `/ark-fix` / `/ark-autopilot`. Extra not on
|
|
223
|
+
→ `/ark-adopt` (advisory). Do not invent `/ark-order`.
|
|
211
224
|
|
|
212
225
|
## Operating rules
|
|
213
226
|
|