arkgate 4.8.1 → 4.8.2
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 +11 -0
- package/README.md +5 -3
- package/dist/{diagnosticCatalog-CSF4N3w8.d.ts → diagnosticCatalog-CPzH-MLN.d.ts} +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/nestjs/index.cjs +1 -1
- package/dist/nestjs/index.js +1 -1
- package/dist/runtime/index.cjs +1 -1
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/index.js +1 -1
- package/docs/README.md +2 -2
- package/docs/agent-guide.md +10 -9
- package/docs/package-surface.md +3 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/templates/agent-skills/README.md +1 -1
- package/templates/agent-skills/ark-adopt/SKILL.md +41 -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 +7 -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 +12 -3
- 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/skills/ark-adopt.md +41 -13
- package/templates/skills/ark-architect.md +4 -4
- package/templates/skills/ark-autopilot.md +22 -4
- package/templates/skills/ark-contract.md +7 -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 +12 -3
- package/templates/skills/ark-runtime.md +13 -11
- package/templates/skills/ark-think.md +13 -7
- package/templates/skills/ark-upgrade.md +12 -4
|
@@ -69,20 +69,22 @@ retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedP
|
|
|
69
69
|
uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
|
|
70
70
|
restart/retargeting is required. `ark://manifest` never satisfies this preflight.
|
|
71
71
|
|
|
72
|
-
## Dual plane — layers +
|
|
72
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
73
73
|
|
|
74
|
-
ArkGate has **
|
|
74
|
+
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.
|
|
75
75
|
|
|
76
76
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
77
77
|
|-------|------------------|----------------|-----------------|
|
|
78
78
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
79
79
|
| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
|
|
80
|
+
| **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`) |
|
|
81
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
80
82
|
|
|
81
83
|
**Rules for every report / answer:**
|
|
82
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
84
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
83
85
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
84
86
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
85
|
-
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).
|
|
87
|
+
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). Extra decisions stay on existing doors. Do not invent `/ark-run` or `/ark-order`.
|
|
86
88
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
87
89
|
|
|
88
90
|
|
|
@@ -90,6 +92,9 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
90
92
|
- For ONE decision, consider options on **both** planes when relevant: e.g. new layer wall **vs** structure sensor **vs** invariant catalog entry.
|
|
91
93
|
- Every option must state enforceability: which plane holds it after the change.
|
|
92
94
|
|
|
95
|
+
### Think + extras
|
|
96
|
+
- Extra decisions stay enforceable on existing doors (`/ark-adopt` session 0, `/ark-place` new file, `/ark-autopilot` grind, `/ark-runtime` one kernel candidate). No new skill name. Do not invent `/ark-run` or `/ark-order`.
|
|
97
|
+
|
|
93
98
|
## Subagent fan-out (optional, host-dependent)
|
|
94
99
|
|
|
95
100
|
When the user asks to go faster **or** the work naturally splits (multiple packages,
|
|
@@ -126,8 +131,9 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
|
|
|
126
131
|
migration cost, **pilot + kill-switch** if the option adds a layer or wall.
|
|
127
132
|
7. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
|
|
128
133
|
judgment auto-apply, codemod engines, or skipping write-gate/CI.
|
|
129
|
-
8. **Hand off** — placement `/ark-place`;
|
|
130
|
-
`/ark-
|
|
134
|
+
8. **Hand off** — placement `/ark-place`; first extra `/ark-adopt`; grind `/ark-autopilot`;
|
|
135
|
+
map-only `/ark-explore`; leftover config `/ark-contract`; leftover cluster `/ark-fix` /
|
|
136
|
+
`/ark-loop`. Extra decisions stay on those doors. Do not invent `/ark-run` or `/ark-order`.
|
|
131
137
|
When the user needs action not advice: **STOP — do not continue this skill as complete** — invoke the handoff skill.
|
|
132
138
|
|
|
133
139
|
## Output format
|
|
@@ -154,7 +160,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
154
160
|
- **Sensor:** commands/tools run
|
|
155
161
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
156
162
|
- **Result:** one-line outcome
|
|
157
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
163
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
158
164
|
- **Compass:** top residual lenses | `n/a`
|
|
159
165
|
- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
|
|
160
166
|
- **Handoff:** `/ark-…` / CLI / `none`
|
|
@@ -116,27 +116,35 @@ a stale MCP is non-authoritative: `ark_identity` diagnoses it and project tools
|
|
|
116
116
|
`PROCESS_PACKAGE_STALE` until restart. Prefer project-local CLI meanwhile. A modern stale global
|
|
117
117
|
`ark upgrade` hands off automatically; pre-4.6.4 globals need one `npx arkgate upgrade` entry.
|
|
118
118
|
|
|
119
|
-
## Dual plane — layers +
|
|
119
|
+
## Dual plane — layers + extras (mandatory, except /ark-runtime)
|
|
120
120
|
|
|
121
|
-
ArkGate has **
|
|
121
|
+
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
122
|
|
|
123
123
|
| Plane | What it protects | Where it lives | Sensors / tools |
|
|
124
124
|
|-------|------------------|----------------|-----------------|
|
|
125
125
|
| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
|
|
126
126
|
| **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`; **`kernelRoots` preferred**, `compositionRoots` alias | `ARKRUN_*`, doctor `arkRun` (`notAScore`) |
|
|
128
|
+
| **ArkOrder** (extra) | Operational pattern (ξ vs s) | `arkOrder` on `ark.config.json` (schema `1.3+`); factory `arkgate/order` | `ARKORDER_*` |
|
|
127
129
|
|
|
128
130
|
**Rules for every report / answer:**
|
|
129
|
-
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a
|
|
131
|
+
1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** or **`[ArkRun]`** or **`[ArkOrder]`** (or a table with those headers).
|
|
130
132
|
2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
|
|
131
133
|
3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
|
|
132
134
|
4. After upgrade, leftover architecture work is **`/ark-autopilot`** (never invent `mechanical-safe`).
|
|
133
135
|
5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
|
|
136
|
+
6. Schema `1.3` extras stay off unless already on. Pin teaches `arkgate/runtime` (same tarball), not the deprecated companion. Do not invent `/ark-run` or `/ark-order`.
|
|
134
137
|
|
|
135
138
|
|
|
136
139
|
### Upgrade + ArkRules
|
|
137
140
|
- Refresh skills + note if templates gained ArkRules deepen; do not force consumers to adopt `arkRules`.
|
|
138
141
|
- After upgrade: doctor `rulesUnderContract` if map exists; dual-truth note if `--no-install` left package pin old.
|
|
139
142
|
|
|
143
|
+
### Upgrade + extras
|
|
144
|
+
- Schema `1.3` extras (`arkRun` / `arkOrder`) stay off unless already on. Do not turn extras on during upgrade.
|
|
145
|
+
- Pin teaches `arkgate/runtime` (same tarball). `@arkgate/runtime` is deprecated. Do not send agents to `packages/runtime/README.md` as the kernel guide.
|
|
146
|
+
- After 4.8.2, customized skills may lag — opt-in `--refresh-skills` with consent so the frozen 13 names pick up four-plane deepen. No new skill names.
|
|
147
|
+
|
|
140
148
|
## Safety contract
|
|
141
149
|
|
|
142
150
|
- Always invoke the **project-local** CLI (`npx arkgate` /
|
|
@@ -305,7 +313,7 @@ End with exactly this structure:
|
|
|
305
313
|
- **Active host:** host and verified status
|
|
306
314
|
- **Deferred hosts:** `none` or host plus future action
|
|
307
315
|
- **Result:** old → new version and managed-upgrade outcome
|
|
308
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
|
|
316
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
309
317
|
- **Compass:** top residual lenses | `n/a`
|
|
310
318
|
- **Handoff:** `/ark-…`, CLI action, or `none`
|
|
311
319
|
- **Incomplete?** `no` or `yes — <missing work>`
|
|
@@ -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,23 +118,25 @@ 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
|
|
@@ -142,7 +146,7 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
142
146
|
|
|
143
147
|
### Adopt + ArkRun
|
|
144
148
|
- 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: `
|
|
149
|
+
- 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
150
|
- Do **not** put `arkRun` on the compact starter / `ark start` scaffold. Brownfield stays advisory until the team promotes.
|
|
147
151
|
- Absence is valid and **silent** — never force the extra. Never force the kernel over existing Nest/DI. Do not invent `/ark-run`.
|
|
148
152
|
- Import from `arkgate/runtime` (factory `createStrictArkKernel`, per instance, no process-wide singleton). `@arkgate/runtime` is deprecated. No shipped cloud broker SDKs.
|
|
@@ -150,6 +154,28 @@ ArkGate has **two opt-in planes**. The user chooses which to use; you **always l
|
|
|
150
154
|
- Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
|
|
151
155
|
- After the extra is honest: handoff `/ark-runtime` to wire one candidate, `/ark-place` for new kernel-managed files. Skills never enforce.
|
|
152
156
|
|
|
157
|
+
### Adopt + ArkOrder
|
|
158
|
+
- 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`.
|
|
159
|
+
- Required shape: `planeRoots` (real files; empty + enforced = `ARKORDER_MISSING_PLANE`), `managedLayers` (existing `layers[].name` only), `maxXiKeys` (default 7).
|
|
160
|
+
- Example (consumer trees — not this library's 4-layer compact):
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"schemaVersion": "1.3",
|
|
165
|
+
"arkOrder": {
|
|
166
|
+
"mode": "advisory",
|
|
167
|
+
"planeRoots": ["src/main.ts"],
|
|
168
|
+
"managedLayers": ["Application"],
|
|
169
|
+
"maxXiKeys": 7
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).
|
|
175
|
+
- Absence is valid and **silent** — never force the extra. Do not invent `/ark-order`.
|
|
176
|
+
- Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
|
|
177
|
+
- After the extra is honest: handoff `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
|
|
178
|
+
|
|
153
179
|
## Subagent fan-out (optional, host-dependent)
|
|
154
180
|
|
|
155
181
|
When the user asks to go faster **or** the work naturally splits (multiple packages,
|
|
@@ -200,8 +226,10 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
|
|
|
200
226
|
**Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
|
|
201
227
|
**ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
|
|
202
228
|
User wants the ArkRun extra → write **advisory** `arkRun` (schema `1.2+`, real
|
|
203
|
-
`compositionRoots
|
|
204
|
-
|
|
229
|
+
`kernelRoots` preferred — `compositionRoots` alias, existing `managedLayers`) **in this turn**.
|
|
230
|
+
User wants the ArkOrder extra → write **advisory** `arkOrder` (schema `1.3+`, real
|
|
231
|
+
`planeRoots`, existing `managedLayers`, `maxXiKeys` 7) **in this turn**. Do not add extras
|
|
232
|
+
to a compact starter. Do not promote to enforced as the session-0 default.
|
|
205
233
|
2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
|
|
206
234
|
Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
|
|
207
235
|
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 +272,9 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
|
|
|
244
272
|
|
|
245
273
|
- Freeze false positives to get green.
|
|
246
274
|
- Force runtime kernel over existing Nest/DI.
|
|
247
|
-
- Put `arkRun` on the compact starter / `ark start` scaffold.
|
|
275
|
+
- Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
|
|
248
276
|
- Claim in-memory kernel stores are production durability.
|
|
249
|
-
- Invent `/ark-run`.
|
|
277
|
+
- Invent `/ark-run` or `/ark-order`.
|
|
250
278
|
- Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
|
|
251
279
|
- End adopt with only “baseline written” when design-weak residual is visible in files you opened.
|
|
252
280
|
|
|
@@ -258,7 +286,7 @@ End with **exactly** these headings (markdown `###`):
|
|
|
258
286
|
- **Sensor:** commands/tools run
|
|
259
287
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
260
288
|
- **Result:** one-line outcome
|
|
261
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** (or `n/a` if unused)
|
|
289
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
262
290
|
- **Compass:** top residual lenses | `n/a`
|
|
263
291
|
- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
|
|
264
292
|
- **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`. Freeze ξ with `release()`; never `update`/`patch`/`set`.
|
|
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,9 @@ 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
45
|
|
|
46
46
|
## Subagent fan-out (optional, host-dependent)
|
|
47
47
|
|
|
@@ -55,9 +55,9 @@ If the host supports **parallel subagents**, fan out read-only scouts; otherwise
|
|
|
55
55
|
|
|
56
56
|
## Steps
|
|
57
57
|
|
|
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.
|
|
58
|
+
1. If the path is missing or lying → execute **`/ark-adopt`** (including first advisory `arkRun` / first advisory `arkOrder`).
|
|
59
|
+
2. If the path is honest and you are tightening rules or extras (`arkRun` / `arkOrder`) → execute **`/ark-autopilot`**.
|
|
60
|
+
3. One kernel candidate (extra already on) → **`/ark-runtime`**. `ark-check --strict-config`.
|
|
61
61
|
|
|
62
62
|
## Completion contract (skill incomplete if missing)
|
|
63
63
|
|
|
@@ -67,7 +67,7 @@ Skill incomplete if missing any field below.
|
|
|
67
67
|
- **Sensor:** commands/tools run
|
|
68
68
|
- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
|
|
69
69
|
- **Result:** one-line outcome
|
|
70
|
-
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** (or `n/a` if unused)
|
|
70
|
+
- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** vs **[ArkOrder]** (or `n/a` if unused)
|
|
71
71
|
- **Compass:** top residual lenses | `n/a`
|
|
72
72
|
- **Handoff:** `/ark-adopt` / `/ark-autopilot` / `none`
|
|
73
73
|
- **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>`
|