arkgate 4.1.1 → 4.2.0

package/schemas/ark.project-identity.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@4/schemas/ark.project-identity.schema.json",
+  "title": "ArkGate MCP project identity",
+  "description": "Stable project binding plus separate runtime and architecture-contract evidence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "projectId",
+    "resolvedRoot",
+    "resolvedConfigPath",
+    "arkgateVersion",
+    "contractHash",
+    "contractSource",
+    "runtimeId",
+    "processStartedAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "projectId": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "resolvedRoot": {
+      "type": "string",
+      "minLength": 1
+    },
+    "resolvedConfigPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "arkgateVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contractHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "contractSource": {
+      "enum": [
+        "project",
+        "default-profile",
+        "manifest"
+      ]
+    },
+    "runtimeId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "processStartedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "$defs": {
+    "expectation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "expectedRoot": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute expected workspace/project directory. The initial authoritative handshake requires the exact project root; descendant calls also require expectedProjectId."
+        },
+        "expectedProjectId": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Project id previously returned by ark_identity or ark_manifest."
+        }
+      }
+    },
+    "binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "authoritative"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "matched",
+            "unverified",
+            "mismatch"
+          ]
+        },
+        "authoritative": {
+          "type": "boolean"
+        },
+        "expectedRoot": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expectedProjectId": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "code": {
+          "enum": [
+            "PROJECT_ROOT_MISMATCH",
+            "PROJECT_ID_MISMATCH",
+            "INVALID_PROJECT_EXPECTATION"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.1.1",
+  "version": "4.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.1.1",
+      "version": "4.2.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-adopt.md

@@ -30,6 +30,15 @@ when design smells remain after the contract is honest.
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.

package/templates/skills/ark-architect.md

@@ -31,6 +31,15 @@ The CLI is a **sensor**, never the whole job. Claiming done without the explorat
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -71,8 +80,9 @@ the same files or weaken the gate.
 
 ## Steps
 
-1. **Detect the shape** — call MCP tool **`ark_recommend`** (or run
-   `ark-check --recommend --json`). Read `archetype`, `preset`, `confidence`,
+1. **Bind and detect the shape** — complete the mandatory `ark_identity` preflight first, then
+   call MCP tool **`ark_recommend`** with the bound `project` envelope (or run the workspace-local
+   `ark-check --recommend --json`). Never use an unverified recommendation. Read `archetype`, `preset`, `confidence`,
    `adoptInOrder.phase1`, `analogy`, `why`, `evidence`, and `requiresConfirmation`.
    Ask at most **two** questions only if `requiresConfirmation` is true (or for compatibility
    with older ArkGate output, `confidence < 0.5`):

package/templates/skills/ark-autopilot.md

@@ -65,6 +65,15 @@ decision-grade explore pass **and** without opening violating files.
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.

package/templates/skills/ark-contract.md

@@ -13,7 +13,8 @@ description: Safely edit ark.config.json layers/rules and arkrules/* (structure
 | Concentrated-edge / false-green STOP from other skills | Full map without config edit → `/ark-explore` |
 
 The **one sanctioned way** to change layers/rules/`intentPrefixes`/includes.
-Also used to **land mined business rules** into the executable manifest (`ark.config.json` + intent naming that `ark://manifest` exposes).
+Also used to **land mined business rules** into the executable manifest (`ark.config.json` +
+intent naming that the project-bound `ark_manifest` tool exposes authoritatively).
 
 
 ## Dual engine (mandatory)
@@ -27,6 +28,15 @@ The CLI is a **sensor**, never the whole job. Claiming done without the explorat
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.

package/templates/skills/ark-coverage.md

@@ -43,6 +43,15 @@ If you did not open source files, the skill is **not complete**.
 Full recon + pattern planning: `/ark-explore`.
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.

package/templates/skills/ark-explain.md

@@ -27,6 +27,15 @@ The CLI is a **sensor**, never the whole job. Claiming done without the explorat
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -146,7 +155,10 @@ when residual signals remain.
 
 ## Spoken / written explanation
 
-1. **Load the real contract**: `ark.config.json`, `ark://manifest` if available, `AGENTS.md`.
+1. **Load the real contract**: `ark.config.json`, `AGENTS.md`, and—when MCP is available—
+   `ark_identity` with the exact project root followed by `ark_manifest` with the same root plus
+   returned project id. `ark://manifest` is compatibility-only and always
+   unverified/non-authoritative.
 2. **If asked generally** ("explain the architecture"), produce a guided tour:
    - Operating mode + governed% (honest: low coverage means green checks almost nothing).
    - Each major layer: name, purpose, one real file from this repo, file count if known.

package/templates/skills/ark-explore.md

@@ -68,6 +68,15 @@ that still matters (dogfood gaps, soft starters, identity drift, **semantic fals
 say so in one line and hand off `stop`.
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.

package/templates/skills/ark-fix.md

@@ -52,6 +52,15 @@ Next: re-run ark-check; shrink baseline if applicable
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -129,7 +138,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 If the “fix” is really a missing business intent or Domain home for a rule:
 
 - Propose intent name + layer placement.
-- Register / place code so `ark://manifest` / config can enforce it.
+- Register / place code so `ark_manifest` / config can enforce it.
 - Do not only delete the import.
 
 ## Rules

package/templates/skills/ark-loop.md

@@ -42,6 +42,15 @@ Pattern bets always have `neverMechanicalSafe: true` — extraction cards only
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -120,8 +129,8 @@ you may run **that one pilot** — never more:
    card: respect the explicit record and do not reconstruct it from raw facts. Read a live card's
    `pilotTarget`, `decisionTarget`, `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`.
 2. Moves are **proposed only** — enumerate the full move set for the pilot anchor, express it as
-   an architecture change map, and validate through the atomic preflight (`ark_prepare_change` /
-   the write gate) **before** any file moves. A move the preflight rejects is a finding, not a
+   an architecture change map, and validate through the atomic preflight (`ark_prepare_change`
+   with the matched `project` envelope / the write gate) **before** any file moves. A move the preflight rejects is a finding, not a
    thing to force.
 3. Never move anything under `app/` or `pages/` (fixed by framework convention). Never merge
    files here — merges are judgment cards for `/ark-architect` / `/ark-fix`.

package/templates/skills/ark-place.md

@@ -36,6 +36,15 @@ The CLI is a **sensor**, never the whole job. Claiming done without the explorat
 
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -66,16 +75,18 @@ the same files or weaken the gate.
 
 ## Steps
 
-1. **Read the contract, not your intuition.** If the `ark` MCP server is available,
-   call the **`ark_place`** tool with the target file path — it returns the layer,
+1. **Read the contract, not your intuition.** If the `ark` MCP server is available, complete
+   the mandatory `ark_identity` preflight first, then call **`ark_place`** with the target file
+   path and bound `project` envelope — it returns the layer,
    its forbidden globals, and exactly which layers the file may / must not import,
    straight from the contract (no guessing). When present, also honor optional
    **`goldenPattern`** (from `.ark/golden-pattern.json`) for **NEW code only** —
    advisory layout norm; never overrides the gate and never clears design-weak.
-   Absent golden is normal. Otherwise load `ark.config.json` and the
-   `ark://manifest` MCP resource (it includes `suggestedLayers` with conventional
-   directories for layers not yet adopted). The project's `AGENTS.md` placement table,
-   if present, is authoritative too.
+   Absent golden is normal. Otherwise load `ark.config.json`; after the matched preflight,
+   `ark_manifest` with the same bound envelope includes `suggestedLayers` with conventional
+   directories for layers not yet adopted. The `ark://manifest` resource is compatibility-only and always
+   unverified/non-authoritative. The project's `AGENTS.md` placement table, if present, is
+   authoritative too.
 2. **Classify the artifact** by what it does, not what it's called:
    - Pure business rules/entities/value objects → domain-model layer.
    - When Domain ArkRules require private state / factories (`aggregate-private-state`,

package/templates/skills/ark-runtime.md

@@ -24,6 +24,14 @@ one feature at a time.
 
 The CLI is a **sensor**, never the whole job. Claiming done without the exploratory bar for this skill is **incomplete**.
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
 
 ## Out of scope for ArkRules
 

package/templates/skills/ark-think.md

@@ -31,6 +31,15 @@ If you lack a product map and the tree is messy: run a **compressed** explore pa
 Never reason only from abstract hexagons. Open real modules before recommending a shape.
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
@@ -71,8 +80,11 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 
 ## Steps
 
-1. **Load the contract** — `ark.config.json`, MCP `ark://manifest` if available, and
-   `ark-check --coverage --json` / `--doctor` for honesty about governed% and false-green.
+1. **Load the contract** — `ark.config.json`; when MCP is available, call `ark_identity` with
+   the exact project root followed by `ark_manifest` with the same root plus returned project
+   id. The `ark://manifest` resource is compatibility-only and always
+   unverified/non-authoritative. Use `ark-check --coverage --json` / `--doctor` for honesty
+   about governed% and false-green.
 2. **Touch the decision surface** — README skim + **≥5 source files** on the feature/package/boundary
    under discussion. Name paths in the answer.
 3. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,

package/templates/skills/ark-upgrade.md

@@ -20,6 +20,15 @@ check) and direct inspection of every managed file the preview will change.
 Neither signal replaces the other.
 
 
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
 ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.