arkgate 4.6.0 → 4.6.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.1 — 2026-08-14
+
+**Patch** over **4.6.0**. Five-door autonomy (skills write or map in-turn; CLI is sensor +
+gate) plus team parliament (law vs feature: stewards, mixed-PR deny, ratchet vs the merge
+base, cheap `--changed` check). Same 13 skill names. Steward identity is a GitHub handle or
+email, not git `user.name`. **No required config migration.**
+
+**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.1.md`).
+
+### Added
+
+- **Five-door autonomy (SK01–SK05):** `/ark-adopt`, `/ark-place`, `/ark-autopilot`,
+  `/ark-explore`, `/ark-upgrade` write or map in the same turn. The other eight names stay
+  installed as shortcuts. Invoking a door is the approval; the CLI does not apply the change.
+- **Team parliament (TW01–TW08):** mixed law+product deny; optional `stewards` (GitHub handle
+  or email); `--contract-session` / `--contract-diff` / `--changed --base` / `--against` /
+  `--persona` / `--author`; `ark status --vs`; doctor `stewardNudge` (ask or show list drift).
+  `stewards` is excluded from the policy hash.
+
+### Changed
+
+- Doctor, compact router, and public lanes prefer the five doors. Historical changelogs stay
+  as shipped.
+
 ## 4.6.0 — 2026-08-12
 
 **Minor** over **4.5.7**. Understandable Ark: doctor, HTML, skills, and public docs use common
@@ -13,7 +37,7 @@ software words (import rules, leftover design work, pre-write block) while **Ark
 “always latest” floor Codex already had. **No required config migration.** JSON field names
 and `ruleId`s stay stable. No new skill names, sensors, or scores.
 
-**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.0.md`).
+**Status: published** (on npm `latest`; see `docs/releases/4.6.0.md`).
 
 ### Added
 

package/README.md

@@ -16,8 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.0** is prepared — clearer language + shared agent home skills.
-> [4.6.0 notes](docs/releases/4.6.0.md) · [4.5.7](docs/releases/4.5.7.md) (npm `latest`) · [4.5.6](docs/releases/4.5.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.0** is on npm `latest` — clearer language + shared agent home skills.
+> [4.6.0 notes](docs/releases/4.6.0.md) · [4.5.7](docs/releases/4.5.7.md) · [4.5.6](docs/releases/4.5.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -48,10 +48,13 @@ dependency inversion — **not a score**). Leftover lenses mean design work may
 imports are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
 
 ```text
-start → doctor (+ compass) → day-to-day (place + gate)
-                         ↘ optional /ark-autopilot after skill pack
+start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
+                         ↘ /ark-explore then /ark-autopilot when leftover design remains
 ```
 
+Teams: keep the constitution out of product PRs. Local gate
+`ark-check --changed --base origin/dev`. Steward law PRs use `--contract-session`.
+
 Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts.
 
 ![Write gate: agent blocked, then self-corrects](docs/assets/ark-write-gate.svg)
@@ -210,7 +213,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.5.7 on npm `latest`) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) · [CHANGELOG](CHANGELOG.md) |
+| Current release (4.6.0 on npm `latest`) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) |
 | Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
 | Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |

package/bin/ark-check-runtime.mjs

@@ -103,6 +103,13 @@ import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement } from './lib/analys
 import { reportUnavailableAnalysis } from './lib/unavailable-analysis.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import { analyzePolicyTransition } from './lib/policy-delta-io.mjs';
+import {
+  applyAgainstRatchet,
+  bindTeamBaseRefs,
+  filterChangedGovernedFiles,
+  runTeamPreflight,
+  ungovernedDumpMessage,
+} from './lib/team-parliament-io.mjs';
 import { tryResidentDoctor } from './lib/resident-doctor-client.mjs';
 import { createDesignDeltaCheck } from './lib/design-delta.mjs';
 import {
@@ -134,6 +141,14 @@ function parseArgs(argv) {
     policyBase: undefined,
     policyBaseRef: undefined,
     policyAck: undefined, failOnNewSmells: false, baseRef: undefined,
+    contractSession: false,
+    contractDiff: false,
+    changed: false,
+    against: undefined,
+    base: undefined,
+    persona: undefined,
+    author: undefined,
+    failUngoverned: false,
     updateBaseline: false,
     noCache: false,
     resident: false,
@@ -241,6 +256,13 @@ function parseArgs(argv) {
     else if (arg === '--policy-base') args.policyBase = requireValue(arg, i++);
     else if (arg === '--policy-base-ref') args.policyBaseRef = requireValue(arg, i++);
     else if (arg === '--policy-ack') args.policyAck = requireValue(arg, i++); else if (arg === '--fail-on-new-smells') args.failOnNewSmells = true; else if (arg === '--base-ref') args.baseRef = requireValue(arg, i++);
+    else if (arg === '--contract-session') args.contractSession = true;
+    else if (arg === '--contract-diff') args.contractDiff = true;
+    else if (arg === '--changed') args.changed = true;
+    else if (arg === '--against') args.against = requireValue(arg, i++);
+    else if (arg === '--base') args.base = requireValue(arg, i++);
+    else if (arg === '--persona') args.persona = requireValue(arg, i++);
+    else if (arg === '--author') args.author = requireValue(arg, i++);
     else if (arg === '--root') args.root = path.resolve(requireValue(arg, i++));
     else if (arg === '--config') args.config = requireValue(arg, i++);
     else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
@@ -265,7 +287,7 @@ function usage() {
   return [
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       ark-check --version',
-    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
@@ -291,6 +313,11 @@ function usage() {
     'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
     'fail the check, so the ratchet only moves toward zero.',
     '',
+    'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
+    'the same diff as product source. --changed --base <ref> checks touched files only.',
+    '--against <ref> ratchets new keys vs that ref\'s baseline. --contract-session is a',
+    'steward law-only PR. Loosen / baseline-grow need stewards[] + --author when set.',
+    '',
     '--init scans the project for the built-in layer directory conventions (src/domain,',
     'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
     'only the layers that actually exist, with the default rules filtered to those layers.',
@@ -546,7 +573,7 @@ function runApplyPolicyPack(args) {
 
   if (fs.existsSync(configPath) && !args.force) {
     console.error(
-      `${configPath} already exists. Re-run with --force to overwrite, or use /ark-contract to evolve it.`
+      `${configPath} already exists. Re-run with --force to overwrite, or use /ark-adopt to evolve it.`
     );
     process.exitCode = 2;
     return;
@@ -1030,7 +1057,7 @@ function runInit(args) {
       console.log('A green check ignores this code; it is not "clean", it is unchecked.');
       if (recognized.length > 0) {
         console.log('');
-        console.log('Proposed layer for each (from the 11-layer profile + presets — apply via /ark-contract):');
+        console.log('Proposed layer for each (from the 11-layer profile + presets — apply via /ark-adopt):');
         for (const p of recognized) {
           const alt = p.alternatives?.length ? ` (or ${p.alternatives.join(' / ')} — confirm)` : '';
           console.log(`  ${p.dir}/ → ${p.layer}${alt}`);
@@ -1281,19 +1308,71 @@ async function main() {
   }
 
   const root = args.root;
+  const bound = bindTeamBaseRefs(args, root);
+  Object.assign(args, bound.args);
   const config = readConfig(root, args.config);
   const policyDelta = analyzePolicyTransition({
     root,
     configPath: args.config,
     candidateConfig: config,
-    strictMerge: args.strictMerge,
+    strictMerge: args.strictMerge || args.contractDiff,
     basePath: args.policyBase,
     baseRef: args.policyBaseRef,
     acknowledgementPath: args.policyAck,
   });
+  const preflight = runTeamPreflight({
+    root,
+    args,
+    config,
+    policyDelta,
+    teamBase: bound.teamBase,
+  });
+  const teamParliament = preflight.teamParliament;
+  const changedPaths = preflight.changedPaths;
+  if (preflight.halt) {
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: preflight.halt.exitCode === 0,
+            ...(preflight.halt.cheap ? { cheap: true } : {}),
+            teamParliament: preflight.halt.teamParliament,
+            ...(policyDelta ? { policyDelta } : {}),
+          },
+          null,
+          2
+        )
+      );
+    } else if (preflight.halt.exitCode === 0) {
+      console.log('✔ Ark check passed (no governed source or constitution files in the diff).');
+    } else {
+      console.error(preflight.halt.message);
+    }
+    process.exitCode = preflight.halt.exitCode;
+    return;
+  }
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
-  const files = collectGovernedFiles(root, config);
+  const allGovernedFiles = collectGovernedFiles(root, config);
+  if (args.failUngoverned && teamParliament?.changeSet?.productPaths?.length) {
+    const governedRel = new Set(
+      allGovernedFiles.map((abs) => normalize(path.relative(root, abs)))
+    );
+    const dumped = teamParliament.changeSet.productPaths.filter((rel) => !governedRel.has(rel));
+    if (dumped.length > 0) {
+      const message = ungovernedDumpMessage(dumped);
+      if (args.json) {
+        console.log(JSON.stringify({ ok: false, teamParliament: { ...teamParliament, ungoverned: dumped }, message }, null, 2));
+      } else {
+        console.error(message);
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const files = args.changed
+    ? filterChangedGovernedFiles(allGovernedFiles, root, changedPaths, normalize)
+    : allGovernedFiles;
 
   // --coverage is a pure glob/report view (no TypeScript resolver), so serve it BEFORE the
   // TS import: the report must work — and exit 0 — even when typescript isn't installed.
@@ -1381,7 +1460,7 @@ async function main() {
       printViolationBreakdown(summary, { toStderr: true });
       console.error('');
       console.error('Freezing this would bury a likely CONTRACT bug as "debt". Fix the contract');
-      console.error('first (/ark-contract), then re-run. To freeze anyway: --update-baseline --force.');
+      console.error('first (/ark-adopt), then re-run. To freeze anyway: --update-baseline --force.');
       process.exitCode = 2;
       return;
     }
@@ -1430,7 +1509,18 @@ async function main() {
   let suppressed = [];
   let activeViolations = violations;
   let staleBaselineKeys = 0;
-  if (args.baseline) {
+  if (args.against) {
+    const ratcheted = applyAgainstRatchet({
+      violations,
+      againstRef: args.against,
+      root,
+      changed: args.changed,
+      changedPaths,
+      occurrenceKeys: baselineOccurrenceKeys(violations),
+    });
+    activeViolations = ratcheted.activeViolations;
+    suppressed = ratcheted.suppressed;
+  } else if (args.baseline) {
     const baseline = readBaseline(root, args.baseline);
     if (baseline.exists) {
       const occurrenceKeys = baselineOccurrenceKeys(violations);
@@ -1755,6 +1845,7 @@ async function main() {
           }
         : {}),
       ...(codexRepoSkillGap ? { codexRepoSkillGap } : {}), ...(policyDelta ? { policyDelta } : {}), ...(designDelta ? { edgeValid: edgeOk, designDelta } : {}),
+      ...(teamParliament ? { teamParliament } : {}),
     }, null, 2));
   } else {
     for (const warning of warnings) {

package/bin/ark-mcp-runtime.mjs

@@ -73,6 +73,8 @@ import {
 } from './lib/prepare-change.mjs';
 import { detectWritePathCapabilities } from './lib/write-path-detect.mjs';
 import { collectGovernedFiles, isGovernableSourceFile } from './lib/scan-files.mjs';
+import { classifyChangeSet, evaluateTeamGate } from './lib/team-parliament.mjs';
+import { contractSessionFrom } from './lib/team-parliament-io.mjs';
 import {
   canonicalizeCandidateChanges,
   resolvedCompilerInputPaths,
@@ -657,6 +659,20 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       return;
     }
     const patchWrites = parsedPatch.writes;
+    const patchChangeSet = classifyChangeSet(patchWrites.map((change) => String(change.path)));
+    const patchLawGate = evaluateTeamGate({
+      changeSet: patchChangeSet,
+      contractSession: contractSessionFrom({}),
+    });
+    if (patchLawGate.deny && patchChangeSet.mixed) {
+      const message = patchLawGate.message;
+      output.stderr(`Ark architecture gate: ${message}\n`);
+      if (grokStyle) {
+        output.stdout(`${JSON.stringify({ decision: 'deny', reason: message })}\n`);
+      }
+      output.status(2);
+      return;
+    }
     const sourceWrites = patchWrites.filter((change) =>
       isGovernableSourceFile(path.basename(String(change.path)))
     );
@@ -1387,7 +1403,7 @@ function printSessionContext(config, profile, forbiddenGlobals, args, configPath
   const governedPercent = coverage?.coverage?.governed?.percent ?? coverage?.governed?.percent;
   if (shouldShowNewHereNudge(args.root, configPath, governedPercent, false)) {
     lines.push('');
-    lines.push('New to Ark? Run /ark-architect or: ark-check --recommend');
+    lines.push('New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend');
   }
 
   process.stdout.write(`${lines.join('\n')}\n`);

package/bin/ark.mjs

@@ -138,6 +138,7 @@ function parseArgs(argv) {
     }
     else if (arg === '--expected-root') args.expectedRoot = path.resolve(requireValue(arg, i++));
     else if (arg === '--expected-project-id') args.expectedProjectId = requireValue(arg, i++);
+    else if (arg === '--vs') args.vs = requireValue(arg, i++);
     else if (arg === '--write') args.write = true;
     else if (arg === '--check') args.check = true;
     else if (arg === '--stdout') args.stdout = true;
@@ -157,7 +158,7 @@ function usage() {
               [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--refresh-skills] [--json] [--no-install] [--no-strict]
   ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
-  ark status  [--root <project>] [--config ark.config.json] [--json]
+  ark status  [--root <project>] [--config ark.config.json] [--json] [--vs <git-ref>]
               [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
   ark agents-md [--root <project>] [--config ark.config.json] [--write] [--check] [--stdout] [--json]
                 [--tools <host>]
@@ -796,7 +797,7 @@ async function start(args) {
     console.log('');
     console.log('Next (the only flow you need):');
     if (falseGreenGap) {
-      console.log('  1. In your agent:  /ark-adopt  (or /ark-contract) — fix the contract first');
+      console.log('  1. In your agent:  /ark-adopt — fix the architecture config first');
       console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
     } else {
       console.log('  1. In your agent:  /ark-autopilot');
@@ -811,7 +812,7 @@ async function start(args) {
     }
     console.log('');
     console.log('Optional later: ark-check --report ark-report.html (captures a day-zero/evolution report).');
-    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-fix · /ark-place · ark upgrade');
+    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-autopilot · /ark-place · ark upgrade');
     return 0;
   } finally {
     rl?.close();
@@ -941,6 +942,7 @@ async function main() {
       expectedProjectId: args.expectedProjectId,
       host: args.tools,
       arkgateVersion: cliVersion(),
+      vs: args.vs,
     });
   }
 

package/bin/lib/agent-projection.mjs

@@ -151,7 +151,7 @@ export function buildAgentProjectionBody(facts) {
         lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read architecture config with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
-        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-contract`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
+        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');
     }
     lines.push('### Enforcement surfaces (authoritative)', '', AGENT_PROJECTION_ENFORCEMENT_SURFACES.map((surface) => `- \`${surface}\``).join('\n'), '');
     return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';