feat(scaffold): default to minimal multiagent block; full contract opt-in via --contract (#610)

Adding gitguardex to a repo injected a 171-line multi-agent contract into
AGENTS.md by default. Default install now ships a ~10-line minimal block
(agent branch + worktree, claim files, finish via PR); the full contract is
opt-in via --contract (alias --full). --minimal/--no-contract force minimal.

ensureAgentsSnippet selects the template by options.contract and never
downgrades an existing full block (line-count detector >40 non-blank lines).
The flag is parsed in the shared parseCommonArgs and forwarded through both
sandbox re-spawn builders (setup + doctor) and the recursive doctor child
argv, so protected-base and nested runs keep the chosen variant.

Tests: flip setup/doctor contract assertions to the new minimal default; add
a CLI test (minimal default -> --contract upgrade -> no-downgrade) and a unit
test guarding both sandbox argv builders forward --contract.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

openspec/changes/agent-claude-lean-install-minimal-multiagent-block-op-2026-06-03-10-12/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-03

openspec/changes/agent-claude-lean-install-minimal-multiagent-block-op-2026-06-03-10-12/notes.md

@@ -0,0 +1,49 @@
+# agent-claude-lean-install-minimal-multiagent-block-op-2026-06-03-10-12 (minimal / T1)
+
+Branch: `agent/claude/lean-install-minimal-multiagent-block-op-2026-06-03-10-12`
+
+Make gitguardex's install lean: default `gx setup`/`gx doctor`/`gx install` inject a
+~10-line **minimal** multi-agent block into a target repo's `AGENTS.md`; the full
+171-line contract becomes opt-in via `--contract` (alias `--full`).
+
+## What / Why
+
+Adding gitguardex dumped a 171-line contract into `AGENTS.md` — heavy and noisy
+("don't want the contract"). Most repos want only the load-bearing rules (branch +
+worktree, claim files, finish via PR) without the full Colony/OpenSpec/token
+appendix. Full contract stays one flag away.
+
+## How
+
+- New `templates/AGENTS.multiagent-safety.min.md` — same
+  `<!-- multiagent-safety:START/END -->` markers, ~8 non-blank lines.
+- `ensureAgentsSnippet(repoRoot, dryRun, options)` picks template by
+  `options.contract`; **never downgrades** — an existing managed block over
+  `FULL_BLOCK_LINE_THRESHOLD` (40 non-blank lines) keeps refreshing from the full
+  template even without the flag.
+- `--contract`/`--full`/`--minimal`/`--no-contract` parsed in shared
+  `parseCommonArgs`; forwarded through sandbox respawn + recursive-doctor argv.
+
+## Verify
+
+- `node --test test/setup.test.js test/doctor.test.js` — contract tests green. The
+  7 remaining failures are pre-existing environment failures (gh/npm/worktree
+  detection), identical on baseline, unaffected by this diff.
+- New test: "setup --contract opts into the full contract; default stays minimal
+  and is never downgraded".
+
+## Out of scope (follow-ups)
+
+- `gx claude install --global` writer.
+- Real gx-native merge gate (`mergeStateStatus` / fail-closed review) — global
+  `/autoship` already gates at the agent level.
+
+## Handoff
+
+- Handoff: change=`agent-claude-lean-install-minimal-multiagent-block-op-2026-06-03-10-12`; branch=`agent/claude/lean-install-minimal-multiagent-block-op-2026-06-03-10-12`; scope=`lean install minimal block + opt-in contract`; action=`commit, then finish via PR`.
+
+## Cleanup
+
+- [ ] Run: `gx branch finish --branch agent/claude/lean-install-minimal-multiagent-block-op-2026-06-03-10-12 --base main --via-pr --wait-for-merge --cleanup`
+- [ ] Record PR URL + `MERGED` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).

src/cli/args.js

@@ -108,6 +108,14 @@ function parseCommonArgs(rawArgs, defaults) {
       options.allowProtectedBaseWrite = true;
       continue;
     }
+    if (arg === '--contract' || arg === '--full') {
+      options.contract = true;
+      continue;
+    }
+    if (arg === '--minimal' || arg === '--no-contract') {
+      options.contract = false;
+      continue;
+    }
     if (Object.prototype.hasOwnProperty.call(options, 'waitForMerge') && arg === '--wait-for-merge') {
       options.waitForMerge = true;
       continue;

src/cli/commands/doctor.js

@@ -81,6 +81,7 @@ function doctor(rawArgs) {
         ...(options.skipAgents ? ['--skip-agents'] : []),
         ...(options.skipPackageJson ? ['--skip-package-json'] : []),
         ...(options.skipGitignore ? ['--no-gitignore'] : []),
+        ...(options.contract ? ['--contract'] : []),
         ...(options.dryRun ? ['--dry-run'] : []),
         // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
         '--no-wait-for-merge',

src/cli/shared/sandbox.js

@@ -162,6 +162,7 @@ function runSetupBootstrapInternal(options) {
     skipPackageJson: options.skipPackageJson,
     skipGitignore: options.skipGitignore,
     allowProtectedBaseWrite: options.allowProtectedBaseWrite,
+    contract: options.contract,
   });
 
   return {
@@ -200,6 +201,7 @@ function buildSandboxSetupArgs(options, sandboxTarget) {
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
   if (options.dryRun) args.push('--dry-run');
+  if (options.contract) args.push('--contract');
   return args;
 }
 

src/cli/shared/scaffolding.js

@@ -162,7 +162,7 @@ function runInstallInternal(options) {
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
 
   if (!options.skipAgents) {
-    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
+    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force), contract: Boolean(options.contract) }));
     operations.push(ensureMonorepoAppsSnippet(repoRoot, Boolean(options.dryRun)));
     operations.push(ensureClaudeAgentsLink(repoRoot, Boolean(options.dryRun)));
   }
@@ -247,7 +247,7 @@ function runFixInternal(options) {
   }
 
   if (!options.skipAgents) {
-    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
+    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force), contract: Boolean(options.contract) }));
     operations.push(ensureMonorepoAppsSnippet(repoRoot, Boolean(options.dryRun)));
     operations.push(ensureClaudeAgentsLink(repoRoot, Boolean(options.dryRun)));
   }

src/doctor/index.js

@@ -119,6 +119,7 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
+  if (options.contract) args.push('--contract');
   if (!options.dropStaleLocks) args.push('--keep-stale-locks');
   args.push(options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
   if (options.verboseAutoFinish) args.push('--verbose-auto-finish');

src/scaffold/index.js

@@ -502,31 +502,54 @@ function removeLegacyManagedRepoFile(repoRoot, relativePath, options = {}) {
   return { status: dryRun ? 'would-remove' : 'removed', file: relativePath };
 }
 
-function ensureAgentsSnippet(repoRoot, dryRun) {
+// A managed block longer than this many non-blank lines is treated as the full
+// contract. The minimal block is ~8 lines and the full contract is ~171, so any
+// threshold between the two is safe; 40 leaves a wide margin on both sides.
+const FULL_BLOCK_LINE_THRESHOLD = 40;
+
+function countNonBlankLines(text) {
+  return text.split('\n').filter((line) => line.trim().length > 0).length;
+}
+
+// Default install ships the minimal block; the full 171-line contract is opt-in
+// via `options.contract` (--contract / --full). Once a repo has the full block,
+// it is never silently downgraded: an existing managed block over the line
+// threshold keeps refreshing from the full template even without the flag.
+function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
-  const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
   const managedRegex = new RegExp(
     `${AGENTS_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
     'm',
   );
 
-  if (!fs.existsSync(agentsPath)) {
+  const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, 'utf8') : null;
+  const existingBlock = existing ? existing.match(managedRegex) : null;
+  const existingIsFull = Boolean(existingBlock)
+    && countNonBlankLines(existingBlock[0]) > FULL_BLOCK_LINE_THRESHOLD;
+  const wantFull = Boolean(options.contract) || existingIsFull;
+
+  const templateFile = wantFull
+    ? 'AGENTS.multiagent-safety.md'
+    : 'AGENTS.multiagent-safety.min.md';
+  const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, templateFile), 'utf8').trimEnd();
+  const variant = wantFull ? 'full contract block' : 'minimal block';
+
+  if (existing == null) {
     if (!dryRun) {
       fs.writeFileSync(agentsPath, `# AGENTS\n\n${snippet}\n`, 'utf8');
     }
-    return { status: 'created', file: 'AGENTS.md' };
+    return { status: 'created', file: 'AGENTS.md', note: variant };
   }
 
-  const existing = fs.readFileSync(agentsPath, 'utf8');
-  if (managedRegex.test(existing)) {
-    const next = existing.replace(managedRegex, snippet);
+  if (existingBlock) {
+    const next = existing.replace(managedRegex, () => snippet);
     if (next === existing) {
-      return { status: 'unchanged', file: 'AGENTS.md' };
+      return { status: 'unchanged', file: 'AGENTS.md', note: variant };
     }
     if (!dryRun) {
       fs.writeFileSync(agentsPath, next, 'utf8');
     }
-    return { status: 'updated', file: 'AGENTS.md', note: 'refreshed gitguardex-managed block' };
+    return { status: 'updated', file: 'AGENTS.md', note: `refreshed gitguardex-managed block (${variant})` };
   }
 
   if (existing.includes(AGENTS_MARKER_START)) {
@@ -538,7 +561,7 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
     fs.writeFileSync(agentsPath, `${existing}${separator}${snippet}\n`, 'utf8');
   }
 
-  return { status: 'updated', file: 'AGENTS.md' };
+  return { status: 'updated', file: 'AGENTS.md', note: variant };
 }
 
 function ensureClaudeAgentsLink(repoRoot, dryRun) {

templates/AGENTS.multiagent-safety.min.md

@@ -0,0 +1,11 @@
+<!-- multiagent-safety:START -->
+## Multi-Agent Safety (minimal)
+
+Guardex is enabled by default. Disable via repo-root `.env` with `GUARDEX_ON=0`.
+
+- Work from an `agent/*` branch + worktree — never edit the protected base (`main`/`dev`) directly. Start with `gx branch start "<task>" "<agent-name>"`, then `cd` into the printed worktree.
+- Claim files before editing: `gx locks claim --branch "<agent-branch>" <file...>`.
+- Finish completed work via PR + cleanup: `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`).
+
+Want the full multi-agent contract (Colony coordination, OpenSpec, token discipline, recovery)? Run `gx setup --contract`.
+<!-- multiagent-safety:END -->

test/doctor.test.js

@@ -128,16 +128,42 @@ Trailing project notes after managed block.
   assert.match(currentAgents, /Trailing project notes after managed block\./);
   assert.match(currentAgents, /Guardex is enabled by default/);
   assert.match(currentAgents, /GUARDEX_ON=0/);
-  assert.match(currentAgents, /GUARDEX_ON=1/);
-  assert.match(currentAgents, /Small tasks stay direct and caveman-only\./);
-  assert.match(currentAgents, /Promote to full Guardex \/ OMX orchestration only when scope grows into:/);
-  assert.match(currentAgents, /final completion\/cleanup section/);
-  assert.match(currentAgents, /PR URL \+ final `MERGED` evidence/);
+  // Default refresh installs the minimal block (full contract is opt-in via --contract).
+  assert.match(currentAgents, /## Multi-Agent Safety \(minimal\)/);
+  assert.match(currentAgents, /gx branch finish .*--via-pr --wait-for-merge --cleanup/);
+  assert.match(currentAgents, /Run `gx setup --contract`/);
+  assert.doesNotMatch(currentAgents, /## Multi-Agent Execution Contract/);
   assert.doesNotMatch(currentAgents, /legacy managed clause/);
   assert.match(result.stdout, /refreshed gitguardex-managed block/);
 });
 
 
+test('setup --contract opts into the full contract; default stays minimal and is never downgraded', () => {
+  const repoDir = initRepo();
+
+  // Default install ships the minimal block, not the 171-line contract.
+  let result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  let agents = fs.readFileSync(path.join(repoDir, 'AGENTS.md'), 'utf8');
+  assert.match(agents, /## Multi-Agent Safety \(minimal\)/);
+  assert.doesNotMatch(agents, /## Multi-Agent Execution Contract/);
+
+  // Opt in: --contract upgrades the managed block to the full contract.
+  result = runNode(['setup', '--target', repoDir, '--no-global-install', '--contract'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  agents = fs.readFileSync(path.join(repoDir, 'AGENTS.md'), 'utf8');
+  assert.match(agents, /## Multi-Agent Execution Contract/);
+  assert.doesNotMatch(agents, /## Multi-Agent Safety \(minimal\)/);
+
+  // No downgrade: a later default run keeps the full contract in place.
+  result = runNode(['setup', '--target', repoDir, '--no-global-install'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  agents = fs.readFileSync(path.join(repoDir, 'AGENTS.md'), 'utf8');
+  assert.match(agents, /## Multi-Agent Execution Contract/);
+  assert.doesNotMatch(agents, /## Multi-Agent Safety \(minimal\)/);
+});
+
+
 test('doctor on protected main auto-runs in a sandbox branch/worktree', () => {
   const repoDir = initRepoOnBranch('main');
   seedCommit(repoDir);