arkgate 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/CHANGELOG.md +1249 -0
  2. package/LICENSE +21 -0
  3. package/README.md +218 -0
  4. package/SECURITY.md +39 -0
  5. package/bin/ark-check.mjs +5204 -0
  6. package/bin/ark-mcp.mjs +898 -0
  7. package/bin/ark-shared.mjs +1520 -0
  8. package/bin/ark.mjs +491 -0
  9. package/dist/eslint/index.cjs +222 -0
  10. package/dist/eslint/index.cjs.map +1 -0
  11. package/dist/eslint/index.d.cts +42 -0
  12. package/dist/eslint/index.d.ts +40 -0
  13. package/dist/eslint/index.js +193 -0
  14. package/dist/eslint/index.js.map +1 -0
  15. package/dist/index.cjs +3080 -0
  16. package/dist/index.cjs.map +1 -0
  17. package/dist/index.d.cts +577 -0
  18. package/dist/index.d.ts +577 -0
  19. package/dist/index.js +2998 -0
  20. package/dist/index.js.map +1 -0
  21. package/dist/nestjs/index.cjs +2332 -0
  22. package/dist/nestjs/index.cjs.map +1 -0
  23. package/dist/nestjs/index.d.cts +22 -0
  24. package/dist/nestjs/index.d.ts +22 -0
  25. package/dist/nestjs/index.js +2308 -0
  26. package/dist/nestjs/index.js.map +1 -0
  27. package/dist/types-DpdVN7Lm.d.cts +1023 -0
  28. package/dist/types-DpdVN7Lm.d.ts +1023 -0
  29. package/docs/agent-guide.md +490 -0
  30. package/docs/ai-gates.md +337 -0
  31. package/docs/ark-check-example.json +87 -0
  32. package/docs/assets/ark-write-gate.svg +28 -0
  33. package/docs/brownfield-adoption.md +87 -0
  34. package/docs/demos/01-write-gate-self-correction.md +74 -0
  35. package/docs/demos/02-brownfield-baseline-adoption.md +71 -0
  36. package/docs/demos/03-copilot-autopilot.md +83 -0
  37. package/docs/enthusiast/README.md +62 -0
  38. package/docs/enthusiast/explanation-application-shape.md +29 -0
  39. package/docs/enthusiast/how-to-agent-gates.md +36 -0
  40. package/docs/enthusiast/how-to-gallery-starter.md +27 -0
  41. package/docs/enthusiast/how-to-pick-shape.md +45 -0
  42. package/docs/enthusiast/how-to-policy-pack.md +37 -0
  43. package/docs/enthusiast/reference-archetypes.md +36 -0
  44. package/docs/enthusiast/reference-commands.md +50 -0
  45. package/docs/enthusiast/tutorial-first-project.md +86 -0
  46. package/docs/production-hardening.md +59 -0
  47. package/package.json +125 -0
  48. package/server.json +39 -0
  49. package/templates/architecture-playbook.json +339 -0
  50. package/templates/policy-packs/enthusiast-feature-sliced.json +20 -0
  51. package/templates/policy-packs/enthusiast-hexagonal.json +18 -0
  52. package/templates/policy-packs/enthusiast-layered.json +18 -0
  53. package/templates/policy-packs/enthusiast-monorepo.json +18 -0
  54. package/templates/skills/ark-adopt.md +103 -0
  55. package/templates/skills/ark-architect.md +90 -0
  56. package/templates/skills/ark-autopilot.md +95 -0
  57. package/templates/skills/ark-contract.md +98 -0
  58. package/templates/skills/ark-coverage.md +96 -0
  59. package/templates/skills/ark-explain.md +78 -0
  60. package/templates/skills/ark-fix.md +96 -0
  61. package/templates/skills/ark-loop.md +69 -0
  62. package/templates/skills/ark-place.md +68 -0
  63. package/templates/skills/ark-runtime.md +62 -0
  64. package/templates/skills/ark-upgrade.md +109 -0
@@ -0,0 +1,83 @@
1
+ # Demo: the co-pilot autopilot, end to end
2
+
3
+ Take a project from "no guardrails" to "governed, cleaned up, and enforced" — the way a
4
+ non-developer would, driving an agent. This is the Phase F→G→H→I flow (plan · guided setup ·
5
+ loop · autopilot) in one sitting.
6
+
7
+ ## In one line
8
+
9
+ `npx ark start` sets it up and shows a plan; **`/ark-autopilot`** (in your agent) carries the
10
+ plan out — applying the safe fixes and proposing the rest, always validated by `ark-check`.
11
+
12
+ ## Prerequisites
13
+
14
+ - Ark built or installed from this repository
15
+ - An agent CLI (Claude, Cursor, Codex, Grok, …) for the `/ark-autopilot` and `/ark-loop` steps
16
+
17
+ ## Steps
18
+
19
+ ### 1. Guided setup (no architecture knowledge needed)
20
+
21
+ ```bash
22
+ TMP=$(mktemp -d); cd "$TMP"
23
+ git init -q # the loop works in a discardable worktree
24
+ npm init -y >/dev/null
25
+ npx ark start --yes
26
+ ```
27
+
28
+ Ark describes the project's shape in plain language, writes `ark.config.json` + agent/CI gates,
29
+ and prints the **plan** — how many fixes are _safe to auto-apply_ vs _need your decision_ —
30
+ plus which **operating mode** applies: **suggest**, **adapt**, or **enforce**.
31
+
32
+ On Nest/Next/express/library projects, init also merges framework filename conventions into
33
+ the layer globs so day-one **governed%** is real (not a false-green empty contract).
34
+
35
+ ### 2. See the plan yourself (optional)
36
+
37
+ ```bash
38
+ npx ark-check --plan # human view (includes Governed: N%)
39
+ npx ark-check --plan --json # { ok, plan: { goal, counts, steps } }
40
+ ```
41
+
42
+ Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence` and a
43
+ plain-language `rationale`. `goal.met` is true only when there are no active violations **and**
44
+ governed coverage is meaningful — so a clean plan that checks almost nothing is not "done."
45
+
46
+ ### 3. Carry the plan out — the autopilot
47
+
48
+ In your agent, run:
49
+
50
+ ```
51
+ /ark-autopilot
52
+ ```
53
+
54
+ It runs the whole flow (newbie tier): confirms the plan, hands off to `/ark-loop` to apply the
55
+ `mechanical-safe` steps one at a time — **validating each with `ark-check` and rolling back any
56
+ regression** — proposes each `judgment` step for a yes/no, loops until `goal.met`, and reports
57
+ what was auto-applied vs proposed vs deferred. Nothing lands until you review the diff.
58
+
59
+ Expert entry: skip the autopilot and use the pieces — `ark init` / `/ark-contract` to shape the
60
+ contract, `ark-check --plan` for the work, `/ark-fix` for targeted fixes, `ark-check
61
+ --strict-config` as the gate. Same contract, same gates; same suggest/adapt/enforce modes.
62
+
63
+ ### 4. It stays clean
64
+
65
+ The gates installed in step 1 keep enforcing the architecture from now on — in CI, and at write
66
+ time if the MCP hook is wired. Verify:
67
+
68
+ ```bash
69
+ npx ark-check --root . --config ark.config.json --strict-config
70
+ ```
71
+
72
+ ## What this proves
73
+
74
+ - **plan + goal** (Phase F): `ark-check --plan` classifies the work and defines "done" (with
75
+ governed% honesty).
76
+ - **guided setup** (Phase G): `ark start` — no preset or skill name required; modes
77
+ suggest / adapt / enforce.
78
+ - **loop** (Phase H): `/ark-loop` — safe, reversible, validated apply.
79
+ - **autopilot** (Phase I): `/ark-autopilot` — the whole thing, with newbie/expert entry styles.
80
+ - **field honesty** (2.0): framework overlays + no false-green at 0% governed.
81
+
82
+ The classifier's precision (only provably-safe changes are ever `mechanical-safe`) is guarded
83
+ by the classifier corpus test in `tests/unit/static-check/arkCheck.test.ts`.
@@ -0,0 +1,62 @@
1
+ # Ark — Architecture Co-pilot (enthusiast track)
2
+
3
+ Plain-language onboarding for builders who use AI agents but are not professional
4
+ developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,
5
+ reference, and explanation.
6
+
7
+ ## How Ark talks to you (2.0)
8
+
9
+ **Entry style** — who is driving: *newbie* (`ark start` / `/ark-autopilot`) vs *expert* (individual commands).
10
+
11
+ **Operating mode** — what Ark is doing right now (one contract underneath):
12
+
13
+ | Mode | Meaning |
14
+ |------|---------|
15
+ | **Suggest** | Propose an application shape and install a starter contract. |
16
+ | **Adapt** | Match the contract to your real layout / raise governed coverage. |
17
+ | **Enforce** | The contract actually governs your code; gates hold the line. |
18
+
19
+ `ark start` and `ark-check --plan` will not claim "everything is guarded" while governed coverage is near zero. On Nest/Next/express starters, init also merges **framework filename conventions** into the layer globs so day-one coverage is real.
20
+
21
+ ## Start here
22
+
23
+ | Type | Document | You will… |
24
+ |------|----------|-----------|
25
+ | **Tutorial** | [First project in 15 minutes](tutorial-first-project.md) | Walk the full path once: recommend → init → verify |
26
+ | **How-to** | [Pick your application shape](how-to-pick-shape.md) | Run `--recommend` / `ark_recommend` and read the plan |
27
+ | **How-to** | [Use a gallery starter](how-to-gallery-starter.md) | Copy a phase-1 scaffold that matches your archetype |
28
+ | **How-to** | [Apply an enthusiast policy pack](how-to-policy-pack.md) | Write `ark.config.json` from a named preset |
29
+ | **How-to** | [Install agent gates](how-to-agent-gates.md) | Wire the write gate and `/ark-*` skills |
30
+ | **Reference** | [Archetypes and presets](reference-archetypes.md) | Look up playbook ids, presets, and phase-1 layers |
31
+ | **Reference** | [Commands and artifacts](reference-commands.md) | `--recommend`, `--write-plan`, `ark-adoption-plan.json`, fix-class JSON |
32
+ | **Explanation** | [Why application shape matters](explanation-application-shape.md) | Understand shapes vs frameworks and progressive phases |
33
+
34
+ ## Public demos (Phase D)
35
+
36
+ Reproducible scripts — no video required:
37
+
38
+ - [Write-gate self-correction](../demos/01-write-gate-self-correction.md)
39
+ - [Brownfield baseline adoption](../demos/02-brownfield-baseline-adoption.md)
40
+ ## Gallery starters
41
+
42
+ | Archetype | Directory |
43
+ |-----------|-----------|
44
+ | `crud-product` | [examples/crud-product-starter](../../examples/crud-product-starter/) |
45
+ | `api-backend` | [examples/api-backend-starter](../../examples/api-backend-starter/) |
46
+ | `worker-pipeline` | [examples/worker-pipeline-starter](../../examples/worker-pipeline-starter/) |
47
+ | `multi-app-workspace` | [examples/multi-app-workspace-starter](../../examples/multi-app-workspace-starter/) |
48
+
49
+ Deep teaching example (runnable API + break exercises): [hexagonal-order-api](../../examples/hexagonal-order-api/).
50
+
51
+ ## Brownfield vs greenfield
52
+
53
+ | Situation | Use |
54
+ |-----------|-----|
55
+ | New or empty repo | `/ark-architect`, `ark-check --recommend`, gallery starters |
56
+ | Existing messy codebase | `/ark-adopt`, [brownfield playbook](../brownfield-adoption.md) |
57
+
58
+ ## Related
59
+
60
+ - [Agent integration guide](../agent-guide.md)
61
+ - [Public demos](../demos/)
62
+ - [Examples index](../../examples/README.md)
@@ -0,0 +1,29 @@
1
+ # Explanation: why application shape matters
2
+
3
+ Ark separates **what you are building** from **which framework you installed**.
4
+
5
+ A “todo app with a database” is an application shape (`crud-product`). Next.js, Vite, or
6
+ Prisma are detection signals that may raise confidence — they do not define the archetype
7
+ label shown to you or your agent.
8
+
9
+ ## Progressive phases
10
+
11
+ Phase 1 is deliberately small (typically 2–4 layers). Phase 2 and 3 unlock when you
12
+ describe new capabilities (payments, email, background jobs, sagas). This keeps enthusiasts
13
+ from drowning in the full 11-layer profile on day one.
14
+
15
+ ## Honesty over green
16
+
17
+ `ark-check --strict-config` and `--coverage` report how much of the tree is actually
18
+ governed. A passing check over 40% of files is not success — Ark says so explicitly.
19
+
20
+ ## Shapes map to presets, not ad-hoc folders
21
+
22
+ Every suggestion traces to `templates/architecture-playbook.json`, named presets, or
23
+ enthusiast policy packs. Agents must not invent `utils/` or `helpers/` as ungoverned dumping
24
+ grounds — classify via `/ark-contract`.
25
+
26
+ ## When not to use enthusiast onboarding
27
+
28
+ Existing large codebases need `/ark-adopt` and the [brownfield playbook](../brownfield-adoption.md):
29
+ diagnose, fix the contract, freeze only real debt, burn down in order.
@@ -0,0 +1,36 @@
1
+ # How to install agent gates
2
+
3
+ ```bash
4
+ npx ark-check --install-agent-gates
5
+ npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
6
+ ```
7
+
8
+ Installs:
9
+
10
+ - Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
11
+ - MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
12
+ - `/ark-*` skills including **`/ark-architect`** and **`/ark-autopilot`**
13
+
14
+ | Host | Extra paths |
15
+ |------|-------------|
16
+ | Claude Code | `.claude/settings.json`, `.claude/skills/` |
17
+ | Cursor | `.cursor/mcp.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
18
+ | Codex | `docs/ark-codex-config.toml` + home MCP/prompts |
19
+ | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
20
+
21
+ ## Session hint
22
+
23
+ `ark-mcp --session-context` appends when governed coverage is low:
24
+
25
+ ```
26
+ New to Ark? Run /ark-architect or: ark-check --recommend
27
+ ```
28
+
29
+ ## Verify gates
30
+
31
+ ```bash
32
+ npx ark-check --doctor
33
+ npx ark-check --require-gates
34
+ ```
35
+
36
+ Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).
@@ -0,0 +1,27 @@
1
+ # How to use a gallery starter
2
+
3
+ Gallery starters are minimal phase-1 scaffolds with a passing `ark-check --strict-config`.
4
+
5
+ ## Copy a starter
6
+
7
+ ```bash
8
+ cp -R path/to/ark/examples/crud-product-starter/. .
9
+ npm install
10
+ npm run check
11
+ ```
12
+
13
+ Pick by archetype — see [examples/README.md](../../examples/README.md).
14
+
15
+ ## When to use a starter vs hexagonal-order-api
16
+
17
+ | Need | Use |
18
+ |------|-----|
19
+ | Fast baseline layout | `*-starter/` gallery |
20
+ | Runnable API + break exercises | `hexagonal-order-api/` |
21
+
22
+ ## After copying
23
+
24
+ 1. Run `ark-check --doctor`
25
+ 2. Install gates: `ark-check --install-agent-gates`
26
+ 3. Use `/ark-place` for new files
27
+ 4. Optionally commit `ark-adoption-plan.json` from `--write-plan` alongside `ark.config.json`
@@ -0,0 +1,45 @@
1
+ # How to pick your application shape
2
+
3
+ ## Terminal
4
+
5
+ ```bash
6
+ npx ark-check --recommend
7
+ npx ark-check --recommend --json
8
+ npx ark-check --recommend --write-plan # also writes ark-adoption-plan.json
9
+ ```
10
+
11
+ ## MCP (agents)
12
+
13
+ Call tool **`ark_recommend`** — same JSON as `--recommend --json`.
14
+
15
+ ## Skill
16
+
17
+ Run **`/ark-architect`** on a greenfield or early-adoption repo.
18
+
19
+ ## What to read in the output
20
+
21
+ | Field | Meaning |
22
+ |-------|---------|
23
+ | `archetype` | Application shape id (`crud-product`, `api-backend`, …) |
24
+ | `preset` | Named Ark layout (`hexagonal`, `layered`, `feature-sliced`, `monorepo`) |
25
+ | `confidence` | How sure the scorer is from repo signals |
26
+ | `adoptInOrder.phase1` | Folders to create first |
27
+ | `analogy` | Plain-language mental model |
28
+ | `antiPatterns` | What Ark will block later |
29
+ | `firstCommand` | Usually `ark init --archetype <id> --yes` |
30
+
31
+ Framework names appear only as secondary `toolHints` in JSON — never as the archetype label.
32
+
33
+ ## Low confidence?
34
+
35
+ If `confidence < 0.5`, ask:
36
+
37
+ 1. Will this app save data between sessions?
38
+ 2. Is this one app or several in one repository?
39
+
40
+ Then re-run `--recommend` or continue with `/ark-architect`.
41
+
42
+ ## Reference
43
+
44
+ Full archetype table: [reference-archetypes.md](reference-archetypes.md). Source of truth:
45
+ `templates/architecture-playbook.json`.
@@ -0,0 +1,37 @@
1
+ # How to apply an enthusiast policy pack
2
+
3
+ Policy packs are thin enthusiast variants over the same preset factories as `ark init --preset`.
4
+
5
+ ## List packs
6
+
7
+ ```bash
8
+ npx ark-check --list-policy-packs
9
+ npx ark-check --list-policy-packs --json
10
+ ```
11
+
12
+ Available packs:
13
+
14
+ - `enthusiast-hexagonal`
15
+ - `enthusiast-layered`
16
+ - `enthusiast-feature-sliced`
17
+ - `enthusiast-monorepo`
18
+
19
+ ## Apply
20
+
21
+ ```bash
22
+ npx ark-check --apply-policy-pack enthusiast-hexagonal
23
+ npx ark-check --root . --config ark.config.json --strict-config
24
+ ```
25
+
26
+ Use `--force` to overwrite an existing `ark.config.json`.
27
+
28
+ Monorepo packs detect workspace roots from `package.json` / `pnpm-workspace.yaml` the same way `--init --preset monorepo` does.
29
+
30
+ ## Packs vs archetypes
31
+
32
+ | You know… | Start with |
33
+ |-----------|------------|
34
+ | Application shape (todo app, API, …) | `ark-check --recommend` → `ark init --archetype` |
35
+ | Preset name only | `--apply-policy-pack enthusiast-<preset>` |
36
+
37
+ `ark-adoption-plan.json` from `--write-plan` includes a suggested `policyPack` id matching the recommended preset.
@@ -0,0 +1,36 @@
1
+ # Reference: archetypes and presets
2
+
3
+ Authoritative source: `templates/architecture-playbook.json` (shipped in the npm package).
4
+
5
+ ## Archetypes (application shape)
6
+
7
+ | Id | Shape | Default preset |
8
+ |----|-------|----------------|
9
+ | `crud-product` | UI + stored data | `hexagonal` |
10
+ | `api-backend` | API server, no UI in repo | `hexagonal` |
11
+ | `frontend-surface` | UI-heavy; backend elsewhere | `layered` / `feature-sliced` |
12
+ | `library-sdk` | Publishable package | `layered` |
13
+ | `cli-utility` | Command-line tool | `layered` |
14
+ | `worker-pipeline` | Background jobs | `hexagonal` |
15
+ | `event-coordinator` | Multi-step processes | `hexagonal` |
16
+ | `integration-bridge` | System glue | `hexagonal` |
17
+ | `multi-app-workspace` | Monorepo | `monorepo` |
18
+ | `prototype-spike` | Quick experiment | `layered` |
19
+
20
+ ## Named presets
21
+
22
+ | Preset | Policy pack |
23
+ |--------|-------------|
24
+ | `hexagonal` | `enthusiast-hexagonal` |
25
+ | `layered` | `enthusiast-layered` |
26
+ | `feature-sliced` | `enthusiast-feature-sliced` |
27
+ | `monorepo` | `enthusiast-monorepo` |
28
+
29
+ ## Gallery mapping
30
+
31
+ | Archetype | Starter |
32
+ |-----------|---------|
33
+ | `crud-product` | `examples/crud-product-starter/` |
34
+ | `api-backend` | `examples/api-backend-starter/` |
35
+ | `worker-pipeline` | `examples/worker-pipeline-starter/` |
36
+ | `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
@@ -0,0 +1,50 @@
1
+ # Reference: commands and artifacts
2
+
3
+ ## Recommendation
4
+
5
+ ```bash
6
+ ark-check --recommend [--json] [--write-plan]
7
+ ```
8
+
9
+ MCP: `ark_recommend` — same JSON body.
10
+
11
+ ## Adoption plan artifact
12
+
13
+ `ark-adoption-plan.json` — optional committed record. Fields:
14
+
15
+ - `archetype`, `preset`, `confidence`
16
+ - `phases` (`1` | `2` | `3` layer lists) and `adoptInOrder.phase1|phase2|phase3`
17
+ - `matchedSignals` — shape signals that drove the score
18
+ - `analogy`, `antiPatterns`, `why`
19
+ - `initCommand`, `firstCommand`, `recommendCommand`, `checkCommand`
20
+ - `galleryStarter`, `policyPack`
21
+
22
+ Never weakens the gate; JSON only.
23
+
24
+ ## Policy packs
25
+
26
+ ```bash
27
+ ark-check --list-policy-packs [--json]
28
+ ark-check --apply-policy-pack <id> [--force]
29
+ ```
30
+
31
+ Pack metadata: `templates/policy-packs/enthusiast-*.json`.
32
+
33
+ ## Init and verify
34
+
35
+ ```bash
36
+ ark init --archetype <id> --yes
37
+ ark-check --doctor [--json]
38
+ ark-check --coverage [--json]
39
+ ark-check --strict-config
40
+ ark-check --report out.html --beginner
41
+ ark-check --watch
42
+ ```
43
+
44
+ ## Violation JSON (enthusiast fields)
45
+
46
+ When present on violations:
47
+
48
+ - `fixClass` — e.g. `port-inversion`, `file-move`
49
+ - `effort` — `small` | `medium`
50
+ - `enthusiastHint` — plain English fix guidance
@@ -0,0 +1,86 @@
1
+ # Tutorial: your first Ark-governed project
2
+
3
+ This tutorial walks one path end-to-end. You need Node 18+ and a new empty folder.
4
+
5
+ ## 1. Create the project
6
+
7
+ ```bash
8
+ mkdir my-app && cd my-app
9
+ npm init -y
10
+ npm install -D arkgate typescript
11
+ ```
12
+
13
+ ## 2. Discover your application shape
14
+
15
+ ```bash
16
+ npx ark-check --recommend
17
+ ```
18
+
19
+ Read the **archetype** (application shape, not “Next.js” or “Prisma”), the **preset**,
20
+ and **phase-1 layers**. If you are unsure, answer the two questions the agent skill
21
+ may ask: “Will this save data?” and “Is this one app or several in one repo?”
22
+
23
+ Optional machine-readable record:
24
+
25
+ ```bash
26
+ npx ark-check --recommend --write-plan
27
+ # -> ark-adoption-plan.json (safe to commit as a team adoption record)
28
+ ```
29
+
30
+ ## 3. Adopt the contract
31
+
32
+ Non-interactive (recommended for scripts):
33
+
34
+ ```bash
35
+ npx ark init --archetype crud-product --yes
36
+ ```
37
+
38
+ Or apply an enthusiast policy pack directly:
39
+
40
+ ```bash
41
+ npx ark-check --list-policy-packs
42
+ npx ark-check --apply-policy-pack enthusiast-hexagonal
43
+ ```
44
+
45
+ ## 4. Scaffold phase-1 folders
46
+
47
+ Create only the directories listed under phase 1 — for a CRUD product typically:
48
+
49
+ ```
50
+ src/domain/
51
+ src/application/
52
+ src/presentation/ # or pages/, components/, http/
53
+ src/adapters/ # persistence implementations
54
+ ```
55
+
56
+ Or copy a [gallery starter](../enthusiast/how-to-gallery-starter.md) and run `npm install && npm run check`.
57
+
58
+ ## 5. Install agent gates
59
+
60
+ ```bash
61
+ npx ark-check --install-agent-gates
62
+ ```
63
+
64
+ This installs `/ark-architect`, `/ark-place`, `/ark-autopilot`, and the other `/ark-*` skills for Claude, Cursor, Codex, Grok, and other detected hosts.
65
+
66
+ ## 6. Verify honestly
67
+
68
+ ```bash
69
+ npx ark-check --doctor
70
+ npx ark-check --coverage
71
+ npx ark-check --root . --config ark.config.json --strict-config
72
+ ```
73
+
74
+ Report `governed.percent` truthfully. An empty layer is fine; an ungoverned `lib/` folder is not.
75
+
76
+ ## 7. Build a feature with the agent
77
+
78
+ Invoke `/ark-architect` once at the start, then `/ark-place` for each new file. The agent
79
+ should place use cases in `application/`, ports in `domain/`, and never import the database
80
+ into `domain/`.
81
+
82
+ ## Next steps
83
+
84
+ - [How to pick your shape](how-to-pick-shape.md)
85
+ - [Public demos](../demos/)
86
+ - [Brownfield adoption](../brownfield-adoption.md) if you already have code
@@ -0,0 +1,59 @@
1
+ # Production Hardening
2
+
3
+ Ark's built-in stores are intentionally in-memory defaults. They are appropriate for tests,
4
+ local development, examples, and single-process demos. Production systems should provide
5
+ stores that match their durability, ordering, retention, and operational requirements.
6
+
7
+ ## In-Memory Defaults
8
+
9
+ These defaults do not survive process restarts:
10
+
11
+ - `InMemoryAuditStore`
12
+ - `InMemoryOutboxStore`
13
+ - `InMemoryReadModelStore`
14
+ - `InMemoryWorkflowStore`
15
+
16
+ Use them only when losing state is acceptable.
17
+
18
+ ## Production Store Checklist
19
+
20
+ When implementing Ark store interfaces in production, cover these guarantees explicitly:
21
+
22
+ - Durability: records survive process restarts and deploys.
23
+ - Idempotency: repeated writes or dispatch attempts do not corrupt state.
24
+ - Ordering: event/outbox ordering is defined where consumers depend on it.
25
+ - Concurrency: simultaneous publishers/workers cannot race checkpoints or workflow state.
26
+ - Retention: audit and trace records have an explicit retention policy.
27
+ - Observability: failed writes and dispatches are visible to operators.
28
+ - Migration: schema changes for stored records are versioned.
29
+
30
+ ## Interface Targets
31
+
32
+ | Concern | Interface |
33
+ |---------|-----------|
34
+ | Audit records | `AuditStore` |
35
+ | Outbox dispatch handoff | `OutboxStore` |
36
+ | Projection state | `ReadModelStore` |
37
+ | Workflow snapshots | `WorkflowStore` |
38
+
39
+ ## Example Shape
40
+
41
+ ```ts
42
+ class DurableAuditStore implements AuditStore {
43
+ async append(record: AuditRecord): Promise<void> {
44
+ // Insert into your database with an idempotent key.
45
+ }
46
+
47
+ async query(query: AuditQuery = {}): Promise<AuditRecord[]> {
48
+ // Apply query filters and retention-aware ordering.
49
+ return [];
50
+ }
51
+
52
+ async clear(): Promise<void> {
53
+ // Usually only enabled in tests or isolated maintenance jobs.
54
+ }
55
+ }
56
+ ```
57
+
58
+ Ark does not ship a database adapter in core because storage choice is operationally
59
+ specific. Keep those adapters in the application or a separate integration package.
package/package.json ADDED
@@ -0,0 +1,125 @@
1
+ {
2
+ "name": "arkgate",
3
+ "version": "2.1.0",
4
+ "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
5
+ "type": "module",
6
+ "main": "./dist/index.cjs",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js",
13
+ "require": "./dist/index.cjs"
14
+ },
15
+ "./eslint": {
16
+ "types": "./dist/eslint/index.d.ts",
17
+ "import": "./dist/eslint/index.js",
18
+ "require": "./dist/eslint/index.cjs"
19
+ },
20
+ "./nestjs": {
21
+ "types": "./dist/nestjs/index.d.ts",
22
+ "import": "./dist/nestjs/index.js",
23
+ "require": "./dist/nestjs/index.cjs"
24
+ },
25
+ "./package.json": "./package.json"
26
+ },
27
+ "bin": {
28
+ "arkgate": "bin/ark.mjs",
29
+ "arkgate-check": "bin/ark-check.mjs",
30
+ "arkgate-mcp": "bin/ark-mcp.mjs",
31
+ "ark": "bin/ark.mjs",
32
+ "ark-check": "bin/ark-check.mjs",
33
+ "ark-mcp": "bin/ark-mcp.mjs"
34
+ },
35
+ "mcpName": "io.github.pedroknigge/arkgate",
36
+ "files": [
37
+ "bin",
38
+ "dist",
39
+ "docs/agent-guide.md",
40
+ "docs/enthusiast",
41
+ "docs/demos",
42
+ "docs/ai-gates.md",
43
+ "docs/ark-check-example.json",
44
+ "docs/assets",
45
+ "docs/brownfield-adoption.md",
46
+ "docs/production-hardening.md",
47
+ "templates",
48
+ "server.json",
49
+ "README.md",
50
+ "CHANGELOG.md",
51
+ "SECURITY.md",
52
+ "LICENSE"
53
+ ],
54
+ "scripts": {
55
+ "build": "tsup",
56
+ "dev": "tsup --watch",
57
+ "test": "vitest",
58
+ "test:run": "vitest run",
59
+ "typecheck": "tsc --noEmit",
60
+ "security:audit": "npm audit --omit=dev --audit-level=high",
61
+ "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
62
+ "eval:agent": "node eval/run.mjs",
63
+ "eval:comparative": "node eval/comparative-run.mjs",
64
+ "clean": "rm -rf dist",
65
+ "release:npm": "node scripts/release-npm.mjs",
66
+ "prepack": "npm run build"
67
+ },
68
+ "peerDependencies": {
69
+ "@nestjs/common": ">=9"
70
+ },
71
+ "peerDependenciesMeta": {
72
+ "@nestjs/common": {
73
+ "optional": true
74
+ }
75
+ },
76
+ "overrides": {
77
+ "vite": "6.4.3",
78
+ "tsup": {
79
+ "esbuild": "0.28.1"
80
+ },
81
+ "bundle-require": {
82
+ "esbuild": "0.28.1"
83
+ }
84
+ },
85
+ "devDependencies": {
86
+ "@nestjs/common": "^11.1.27",
87
+ "@types/node": "^20.14.0",
88
+ "reflect-metadata": "^0.2.2",
89
+ "rxjs": "^7.8.2",
90
+ "tsup": "^8.1.0",
91
+ "typescript": "^5.5.3",
92
+ "vitest": "^3.2.6"
93
+ },
94
+ "engines": {
95
+ "node": ">=18"
96
+ },
97
+ "keywords": [
98
+ "arkgate",
99
+ "architecture",
100
+ "architecture-gate",
101
+ "ai-agents",
102
+ "mcp",
103
+ "write-gate",
104
+ "hexagonal",
105
+ "clean-architecture",
106
+ "layered-architecture",
107
+ "import-rules",
108
+ "dependency-rules",
109
+ "boundaries",
110
+ "co-pilot",
111
+ "governance",
112
+ "typescript",
113
+ "eslint",
114
+ "nestjs",
115
+ "architecture-enforcement"
116
+ ],
117
+ "license": "MIT",
118
+ "repository": {
119
+ "type": "git",
120
+ "url": "git+https://github.com/pedroknigge/ark-runtime-kernel.git"
121
+ },
122
+ "publishConfig": {
123
+ "access": "public"
124
+ }
125
+ }