@ngockhoale/ukit 3.4.68 → 3.4.70

package/template_project/.claude/hooks/handoff-model-guard.sh

@@ -563,13 +563,458 @@ function patchTargets(input) {
   return { paths, unparseable };
 }
 
+// ---- Owner-authorized docs-only git publication (create scope) ------------------
+// The shell-write rule blocks every git commit/push in a planning session. The ONE
+// exception: an explicit OWNER message in the same session authorizes a single,
+// strictly parsed `git commit`/`git push` whose staged files (commit) or every
+// outgoing commit's files (push) are docs-scope. Trust rules:
+//   - Only real user turns of the three known host shapes count (mirrors
+//     handoff-intent.mjs structure rules). Assistant prose, tool_result round-trips
+//     and the command template itself ("NO git commit. NO git push.") never authorize.
+//   - The LATEST qualifying owner text decides (a later revocation wins; a later
+//     re-grant is honored). Text evidence only RELAXES an already-proven create
+//     scope — it never mints ownership, and no TTL marker file participates.
+// Per-op, affirmative, docs-explicit grants. "publish" is deliberately NOT a
+// grant word (ambiguous with npm publish). A grant must name BOTH the exact
+// operation (commit vs push — a commit grant never authorizes a push) AND the
+// docs scope. The newest DECISIVE owner text per op wins: an explicit negative
+// ("do not commit") revokes; questions ("why did push fail?"), history
+// ("the push failed yesterday") and wholly quoted text are NOT orders — they
+// neither grant nor revoke, and the scan continues to older turns.
+// NOTE: JS \b is ASCII-only, so Vietnamese words like "đẩy"/"tạo"/"đừng" can
+// NEVER match \b...\b (đ is not an ASCII word char). Explicit lookarounds keep
+// the same "standalone word" semantics for every script.
+const ownerWord = (core) => new RegExp(`(?<![A-Za-z0-9_])(?:${core})(?![A-Za-z0-9_])`, 'iu');
+const OWNER_PUB_OP = {
+  commit: ownerWord('commit'),
+  push: ownerWord('push|đẩy'),
+};
+const OWNER_NEG = "(?:no|not|don'?t|do\\s+not|never|without|không|đừng|chưa)";
+const OWNER_PUB_VETO_OP = {
+  commit: new RegExp(`(?<![A-Za-z0-9_])${OWNER_NEG}(?![A-Za-z0-9_])[^.\\n]{0,30}?(?<![A-Za-z0-9_])commit(?![A-Za-z0-9_])`, 'iu'),
+  push: new RegExp(`(?<![A-Za-z0-9_])${OWNER_NEG}(?![A-Za-z0-9_])[^.\\n]{0,30}?(?<![A-Za-z0-9_])(?:push|đẩy)(?![A-Za-z0-9_])`, 'iu'),
+};
+const OWNER_DOCS_SCOPE = /(?<![A-Za-z0-9_])(?:docs|documentation|tài\s+liệu)(?![A-Za-z0-9_])/iu;
+const OWNER_PUB_CREATE = /(?<![A-Za-z0-9_])(?:create|new|tạo)(?![A-Za-z0-9_])/iu;
+// A grant must be an AFFIRMATIVE ORDER in command position: after optional
+// politeness/filler lead words, a line must OPEN with a publication/create
+// imperative. Merely mentioning the op ("the docs push is pending",
+// "docs commit status", "I mentioned push in docs") is not an order — absence
+// of a negative is never proof of an order.
+const OWNER_LEAD = '(?:(?:please|hãy|vui\\s+lòng|làm\\s+ơn|ok|okay|now|go\\s+ahead(?:\\s+and)?|giúp(?:\\s+tôi)?|then|next|sau\\s+đó|luôn)[,.!]?\\s*)*';
+const OWNER_ORDER_LINE = new RegExp(`^${OWNER_LEAD}(?:commit|push|đẩy|create|tạo)(?=[\\s.,;:!]|$)`, 'iu');
+function opOrderedOnLine(text, op) {
+  for (const line of String(text).split('\n')) {
+    if (OWNER_ORDER_LINE.test(line) && OWNER_PUB_OP[op].test(line)) return true;
+  }
+  return false;
+}
+const OWNER_PUB_NON_ORDER = /\?|\b(?:why|how|when|what|where|who|which|did|didn|doesn|was|were|had|has|should|could|would|can|failed|failing|failure|yesterday|earlier|previously|remember)\b/iu;
+// Same bound as the shared session-intent scan window (32 MiB): a bounded tail
+// read, never a whole-file read, and only when a git publication is attempted.
+const OWNER_TAIL_BYTES = 32 * 1024 * 1024;
+
+function whollyQuoted(text) {
+  const t = String(text).trim();
+  if (t.length < 2) return false;
+  const pairs = { '"': '"', "'": "'", '`': '`', '“': '”', '‘': '’', '«': '»' };
+  return Boolean(pairs[t[0]]) && pairs[t[0]] === t[t.length - 1];
+}
+
+// Bounded scan: read only the last OWNER_TAIL_BYTES of the transcript — the
+// same 32 MiB bound as the shared session-intent window — via a positioned
+// read; the whole file is never loaded, and the scan runs only when a git
+// publication is attempted.
+async function readOwnerTail(p) {
+  try {
+    const fd = await fsp.open(p, 'r');
+    try {
+      const st = await fd.stat();
+      if (!st.isFile() || st.size === 0) return '';
+      const len = Math.min(st.size, OWNER_TAIL_BYTES);
+      const buf = Buffer.alloc(len);
+      const { bytesRead } = await fd.read(buf, 0, len, st.size - len);
+      let s = buf.subarray(0, bytesRead).toString('utf8');
+      if (len < st.size) { const nl = s.indexOf('\n'); if (nl < 0) return ''; s = s.slice(nl + 1); }
+      return s;
+    } finally { await fd.close(); }
+  } catch { return ''; }
+}
+
+function commandTemplateBlock(text) {
+  if (/<command-name>|<command-args>/.test(text)) return true;
+  const firstLine = String(text).split('\n').find((l) => l.trim()) || '';
+  return /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?handoff-(?:create|fullstack|implement|review|status|clear)(?![\w-])/.test(firstLine);
+}
+
+// Text blocks of a user turn (owner words), or null when the entry is not a user
+// turn of a known host shape. Tool-output blocks and command-template turns are
+// dropped: they are never the owner's own words.
+function ownerUserBlocks(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  // Session bind + sidechain exclusion: a grant is only valid from THIS session's
+  // own top-level user turns. Subagent sidechains and foreign-session entries are
+  // never owner words, even when they carry a matching payload shape.
+  if (entry.isSidechain === true || String(entry.isSidechain) === 'true') return null;
+  const sid = entry.sessionId ?? entry.session_id;
+  if (sid !== undefined && sid !== null && String(sid) !== '') {
+    const cur = payload?.session_id ?? payload?.sessionId;
+    if (cur !== undefined && cur !== null && String(cur) !== '' && String(sid) !== String(cur)) return null;
+  }
+  let content = null;
+  if (entry.type === 'user' && entry.message?.role === 'user') content = entry.message.content;
+  else if (entry.type === 'message' && entry.message?.role === 'user') content = entry.message.content;
+  else if (entry.type === 'response_item' && entry.payload?.type === 'message' && entry.payload?.role === 'user') content = entry.payload.content;
+  else return null;
+  if (typeof content === 'string') return commandTemplateBlock(content) ? [] : [content];
+  if (!Array.isArray(content)) return [];
+  const blocks = [];
+  for (const b of content) {
+    if (!b || typeof b !== 'object') continue;
+    if (b.type === 'tool_result' || b.type === 'toolResult' || b.type === 'tool-result') continue;
+    if ((b.type === 'text' || b.type === 'input_text') && typeof b.text === 'string' && !commandTemplateBlock(b.text)) blocks.push(b.text);
+  }
+  return blocks;
+}
+
+// -> { commit: {ok, creation}, push: {ok, creation} } — per-op, newest decisive
+// owner text decides independently for each operation.
+let ownerPubMemo = null;
+async function ownerGitPublishAuthorized() {
+  if (ownerPubMemo !== null) return ownerPubMemo;
+  const res = {
+    commit: { ok: false, creation: false },
+    push: { ok: false, creation: false },
+  };
+  const transcriptPath = typeof payload?.transcript_path === 'string' ? payload.transcript_path : '';
+  if (transcriptPath) {
+    const lines = (await readOwnerTail(transcriptPath)).split('\n');
+    const decided = { commit: false, push: false };
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      let entry;
+      try { entry = JSON.parse(lines[i]); } catch { continue; }
+      const blocks = ownerUserBlocks(entry);
+      if (blocks === null) continue;
+      for (let bi = blocks.length - 1; bi >= 0; bi -= 1) {
+        const b = blocks[bi];
+        if (whollyQuoted(b)) continue; // quoted text is never an order (nor a revocation)
+        for (const op of ['commit', 'push']) {
+          if (decided[op] || !OWNER_PUB_OP[op].test(b)) continue;
+          if (OWNER_PUB_VETO_OP[op].test(b)) { decided[op] = true; continue; } // explicit revocation stays denied
+          if (!opOrderedOnLine(b, op)) continue; // mention/status/report: not an affirmative order
+          if (OWNER_PUB_NON_ORDER.test(b)) continue; // question/history wording: not an order, keep scanning
+          if (!OWNER_DOCS_SCOPE.test(b)) continue; // the order must name the docs scope
+          decided[op] = true;
+          res[op] = { ok: true, creation: OWNER_PUB_CREATE.test(b) };
+        }
+      }
+      if (decided.commit && decided.push) break;
+    }
+  }
+  ownerPubMemo = res;
+  return ownerPubMemo;
+}
+
+// Strict tokenizer for the exception command: plain argv words only, single- and
+// double-quoted literals allowed; any redirect/meta/expansion/glob character
+// (`; | & < > ( ) $ \` * ? [ ] { } # ~ !`) is outside the grammar and returns null.
+function tokenizeStrict(text) {
+  const tokens = [];
+  let cur = '';
+  let has = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === "'") {
+      const end = text.indexOf("'", i + 1);
+      if (end === -1) return null;
+      cur += text.slice(i + 1, end);
+      has = true;
+      i = end;
+    } else if (ch === '"') {
+      let j = i + 1;
+      for (;;) {
+        if (j >= text.length) return null;
+        if (text[j] === '\\' && (text[j + 1] === '"' || text[j + 1] === '\\')) { cur += text[j + 1]; j += 2; continue; }
+        if (text[j] === '"') break;
+        if (text[j] === '$' || text[j] === '`') return null;
+        cur += text[j];
+        j += 1;
+      }
+      has = true;
+      i = j;
+    } else if (ch === '\\') {
+      if (i + 1 >= text.length) return null;
+      cur += text[i + 1];
+      has = true;
+      i += 1;
+    } else if (/\s/.test(ch)) {
+      if (has) { tokens.push(cur); cur = ''; has = false; }
+    } else if (';|&<>()$`*?[]{}#~!'.includes(ch)) {
+      return null;
+    } else {
+      cur += ch;
+      has = true;
+    }
+  }
+  if (has) tokens.push(cur);
+  return tokens;
+}
+
+// -> { op: 'commit' } | { op: 'push', positionals } | null for anything else.
+// Strict: NO git global options at all (`-C`, `-c`, `--git-dir`, `--work-tree`,
+// `--exec`-class redirects cannot be verified, so they are denied, not sanitized),
+// a fixed option allowlist per subcommand, and plain-ref positionals only.
+function parseGitPublication(seg) {
+  if (!seg || seg.sep || seg.heredoc) return null;
+  const tokens = tokenizeStrict(seg.text);
+  if (!tokens || tokens.length < 2 || tokens[0].replace(/^.*\//, '') !== 'git') return null;
+  const sub = tokens[1];
+  const rest = tokens.slice(2);
+  if (sub === 'commit') {
+    for (let i = 0; i < rest.length; i += 1) {
+      const t = rest[i];
+      if (t === '-m' || t === '--message') { i += 1; if (i >= rest.length) return null; continue; }
+      if (t.startsWith('--message=')) continue;
+      if (/^-m[^-]/.test(t) && t.length > 2) continue;
+      if (t === '--allow-empty' || t === '-q' || t === '--quiet') continue;
+      return null;
+    }
+    return { op: 'commit' };
+  }
+  if (sub !== 'push') return null;
+  const benign = new Set(['-q', '--quiet', '-v', '--verbose', '--dry-run', '-u', '--set-upstream', '--progress']);
+  const positionals = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const t = rest[i];
+    if (benign.has(t)) continue;
+    if (t.startsWith('-')) return null; // force/mirror/all/tags/delete/… stay denied
+    // Plain ref names only: a `src:dst` refspec redirects the destination and is
+    // never verified here; `:ref` deletes.
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(t)) return null;
+    positionals.push(t);
+    if (positionals.length > 2) return null;
+  }
+  return { op: 'push', positionals };
+}
+
+function gitRead(...args) {
+  try {
+    const { execFileSync } = require('child_process');
+    return execFileSync('git', ['-C', projectRoot, ...args], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 4 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+// docs-only means the 'allow-doc' class exactly: a staged/outgoing test file is
+// still outside the publication scope (create sessions write docs; tests ship
+// with the implementation cycle).
+function firstOutOfScopePath(names) {
+  for (const n of names) {
+    if (String(n).length && classifyScopePath(String(n).replace(/\\/g, '/')) !== 'allow-doc') return n;
+  }
+  return null;
+}
+
+// Regular-file docs only: a symlink (120000) or submodule/gitlink (160000) under
+// docs/ is a non-blueprint payload even though its path looks like docs.
+const REGULAR_FILE_MODES = new Set(['100644', '100755']);
+function nonRegularDocsPayload(entries) {
+  for (const e of entries) {
+    if (!REGULAR_FILE_MODES.has(e.mode)) return e.path;
+  }
+  return null;
+}
+
+// `git diff --cached --raw -z --no-renames` => ":<srcmode> <dstmode> <sha> <sha> <status>\0<path>\0"
+// --no-renames is mandatory: rename detection would show only the NEW path and
+// hide a source→docs move whose old path is source.
+function parseRawZ(out) {
+  const parts = String(out).split('\0');
+  const entries = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const meta = parts[i];
+    if (!meta) continue;
+    const m = /^:\d+ (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z])/.exec(meta);
+    if (!m) return null;
+    const p = parts[i + 1];
+    i += 1;
+    if (p === undefined || p === '') return null;
+    entries.push({ mode: m[1], status: m[2], path: p });
+  }
+  return entries;
+}
+
+function stagedDocsDenial() {
+  const out = gitRead('diff', '--cached', '--raw', '-z', '--no-renames');
+  if (out === null) return 'the staged file set could not be read (git diff --cached failed)';
+  const entries = parseRawZ(out);
+  if (entries === null) return 'the staged file set could not be parsed';
+  if (entries.length === 0) return 'nothing is staged — stage the docs files first';
+  const bad = firstOutOfScopePath(entries.map((e) => e.path));
+  if (bad) return `staged path '${bad}' is not a docs path (owner publication is docs-only)`;
+  const nonReg = nonRegularDocsPayload(entries.filter((e) => e.status !== 'D'));
+  if (nonReg) return `staged path '${nonReg}' is a symlink or submodule, not a regular docs file`;
+  return '';
+}
+
+// Push config that can widen or REDIRECT the pushed set/destination. The local
+// upstream alone is NOT proof of the destination: remote.<r>.push refspecs,
+// remote.<r>.mirror, push.followTags, branch.<b>.pushRemote and
+// remote.pushDefault can all change what a plain `git push` actually sends.
+function pushConfigDenial(remote, branch) {
+  const truthy = (v) => v !== null && !['false', '0', 'no', 'off'].includes(String(v).trim().toLowerCase());
+  const wide = [];
+  if (truthy(gitRead('config', '--get-all', 'push.followTags'))) wide.push('push.followTags widens the pushed set with tags');
+  if (truthy(gitRead('config', '--get-all', `remote.${remote}.mirror`))) wide.push(`remote.${remote}.mirror redirects/widens the push`);
+  if ((gitRead('config', '--get-all', 'remote.pushDefault') || '').trim()) wide.push('remote.pushDefault redirects the push destination');
+  if (branch && (gitRead('config', '--get-all', `branch.${branch}.pushRemote`) || '').trim()) wide.push(`branch.${branch}.pushRemote redirects the push destination`);
+  if ((gitRead('config', '--get-all', `remote.${remote}.push`) || '').trim()) wide.push(`remote.${remote}.push refspec config redirects the pushed set`);
+  const pdRaw = (gitRead('config', '--get-all', 'push.default') || '').trim();
+  if (pdRaw) {
+    const vals = pdRaw.split('\n').map((s) => s.trim()).filter(Boolean);
+    if (vals.some((v) => !['simple', 'current', 'upstream', 'tracking', 'nothing'].includes(v))) {
+      wide.push(`push.default=${vals.join(',')} widens the pushed set beyond the verified ref`);
+    }
+  }
+  return wide.length ? `push config cannot be verified here: ${wide.join('; ')}` : '';
+}
+
+// Push verifies the OUTGOING COMMITS, not the net tree diff: a commit that added
+// source and a later commit that reverted it hide each other in `diff A..B` but
+// both go to the remote. Every outgoing commit's changed files must be docs-scope,
+// every git read is failclosed, and the destination is pinned to the verified
+// upstream (or, for a brand-new remote branch, to an explicit owner "create"
+// order with a docs-only root off the remote default head).
+function pushOutgoingDocsDenial(positionals, grant) {
+  const pos = Array.isArray(positionals) ? positionals : [];
+  const head = (gitRead('rev-parse', '--abbrev-ref', 'HEAD') || '').trim();
+  if (!head) return 'the current branch could not be read';
+  const noUpstreamMsg = 'the outgoing set cannot be verified — a first push of a new branch needs an explicit "git push -u <remote> <branch>" plus an owner order that says create/new; otherwise push once from an implementation session or configure upstream first';
+  let remote; let tracking; let creating = false;
+  if (pos.length === 0) {
+    tracking = (gitRead('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}') || '').trim();
+    if (!tracking) return noUpstreamMsg;
+    remote = tracking.split('/')[0];
+  } else if (pos.length === 1) {
+    remote = pos[0];
+    tracking = `${remote}/${head}`;
+  } else {
+    remote = pos[0];
+    const br = pos[1].replace(/^refs\/heads\//, '');
+    if (br !== head) return `the pushed branch '${br}' is not the current branch ('${head}') — destination refspecs are not verified here`;
+    tracking = `${remote}/${br}`;
+  }
+  const trackingExists = gitRead('rev-parse', '--verify', '--quiet', `${tracking}^{commit}`) !== null;
+  if (!trackingExists && !creating) {
+    if (pos.length === 0) return noUpstreamMsg;
+    const cfgDeny = pushConfigDenial(remote, head);
+    if (cfgDeny) return cfgDeny;
+    if (!grant || !grant.creation) return `creating remote branch '${tracking.split('/')[1]}' needs an owner order that explicitly says create/new (e.g. "create branch and push the docs") — a plain push order cannot bound the outgoing set here`;
+    creating = true;
+  }
+  if (creating) {
+    // Bounded creation against the LIVE remote baseline, never a cached ref.
+    // ls-remote failure (null) denies; an empty listing is a real empty remote
+    // only when the command itself succeeded (exit 0 with no output).
+    // NOT --heads: that filter drops the HEAD/symref line the default-head pin needs.
+    const live = gitRead('ls-remote', '--symref', remote);
+    if (live === null) return `the live remote listing for '${remote}' could not be read — the creation baseline cannot be proven, so the push is denied`;
+    const heads = live.split('\n').filter((l) => /^[0-9a-f]{40}\trefs\/heads\//.test(l));
+    const headSymref = live.split('\n').find((l) => /^ref: refs\/heads\/\S+\tHEAD$/.test(l));
+    if (heads.some((l) => l.endsWith(`\trefs/heads/${head}`))) {
+      return `remote branch '${head}' already exists — a create order cannot re-create or bypass pinning for an existing branch`;
+    }
+    let base = null;
+    if (heads.length > 0) {
+      if (!headSymref) return `the live remote default head of '${remote}' is unknown — the creation outgoing set cannot be bounded [live=${JSON.stringify(live.slice(0, 200))}]`;
+      const defBranch = headSymref.replace(/^ref: refs\/heads\//, '').replace(/\tHEAD$/, '');
+      const defLine = heads.find((l) => l.endsWith(`\trefs/heads/${defBranch}`));
+      if (!defLine) return `the live remote default head '${defBranch}' has no commit — the creation outgoing set cannot be bounded`;
+      base = defLine.split('\t')[0];
+      if (gitRead('cat-file', '-e', `${base}^{commit}`) === null) {
+        return `the live remote default head ${base.slice(0, 10)} is not present locally — the creation outgoing set cannot be bounded`;
+      }
+    }
+    return verifyOutgoing(base, head, `creating ${tracking}`);
+  }
+  const cfgDeny = pushConfigDenial(remote, head);
+  if (cfgDeny) return cfgDeny;
+  const upstream = (gitRead('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}') || '').trim();
+  if (upstream !== tracking) return `the push target '${tracking}' does not match this branch's upstream${upstream ? ` '${upstream}'` : ' (none set)'} — the actual destination cannot be pinned, so it is denied`;
+  if ((gitRead('rev-list', '--count', `HEAD..${tracking}`) || '1').trim() !== '0') {
+    return `the local branch has diverged from ${tracking} — the push would be non-fast-forward`;
+  }
+  // Pin the ACTUAL destination: a stale remote-tracking ref (e.g. the remote was
+  // rewound after the local ref was recorded) can make a source-carrying push
+  // look like a no-op or docs-only. The local ref must equal the remote's real
+  // head right now; an unreadable answer denies.
+  const localTip = (gitRead('rev-parse', '--verify', '--quiet', `${tracking}^{commit}`) || '').trim();
+  const remoteTip = (gitRead('ls-remote', remote, `refs/heads/${head}`) || '').split('\t')[0].trim();
+  if (!localTip || !remoteTip || localTip !== remoteTip) {
+    return `the remote-tracking ref '${tracking}' does not match the remote's actual head (refs/heads/${head}) — a stale ref cannot bound the destination, so the push is denied`;
+  }
+  return verifyOutgoing(tracking, head, '');
+}
+
+// Lists rev..head and checks every commit is docs-scope. Every git read is
+// failclosed: a failed rev-list or diff-tree DENIES (never silently allows).
+function verifyOutgoing(base, localRef, what) {
+  const revsOut = base === null ? gitRead('rev-list', localRef) : gitRead('rev-list', `${base}..${localRef}`);
+  if (revsOut === null) return `the outgoing commits could not be listed (git rev-list failed${what ? ` for ${what}` : ''}) — denied`;
+  const revs = revsOut.split('\n').map((s) => s.trim()).filter(Boolean);
+  if (revs.length === 0) return ''; // nothing outgoing: the push is a no-op
+  if (revs.length > 400) return `${revs.length} outgoing commits exceed the verification bound`;
+  for (const sha of revs) {
+    const raw = gitRead('diff-tree', '--root', '-r', '-m', '--no-renames', '--no-commit-id', '-z', sha);
+    if (raw === null) return `outgoing commit ${sha.slice(0, 10)} could not be inspected (git diff-tree failed) — denied`;
+    const entries = parseRawZ(raw);
+    if (entries === null || entries.length === 0) return `outgoing commit ${sha.slice(0, 10)} could not be parsed — denied`;
+    const bad = firstOutOfScopePath(entries.map((e) => e.path));
+    if (bad) return `outgoing commit ${sha.slice(0, 10)} touches '${bad}', which is not a docs path (publication is docs-only)`;
+    const nonReg = nonRegularDocsPayload(entries.filter((e) => e.status !== 'D'));
+    if (nonReg) return `outgoing commit ${sha.slice(0, 10)} adds '${nonReg}' as a symlink or submodule, not a regular docs file`;
+  }
+  return '';
+}
+
+async function ownerGitPublishDenial(pub) {
+  const grants = await ownerGitPublishAuthorized();
+  const grant = grants[pub.op];
+  if (!grant || !grant.ok) {
+    return `the owner has not explicitly ordered a docs-only ${pub.op} in this session — an affirmative owner message naming "${pub.op}" and the docs scope is required; questions, history, quoted text, assistant text, tool output and this command's own "NO git commit" text never authorize`;
+  }
+  return pub.op === 'commit' ? stagedDocsDenial() : pushOutgoingDocsDenial(pub.positionals, grant);
+}
+
 // createScopeVerdict({toolName, filePath, filePaths, command, projectDir, intent})
 //   -> {block:boolean, cls:string, reason?:string}
 async function createScopeVerdict({ toolName: tool, filePath, filePaths, command, projectDir, intent, patchUnparseable }) {
   if (intent !== 'create') return { block: false, cls: 'not-create' };
   const alt = 'Write docs/tests only, or run /ukit:handoff-fullstack (or start a new session) to change source.';
   if (tool === 'Bash') {
-    if (!shellWriteHit(String(command || ''))) return { block: false, cls: 'shell-read' };
+    const cmdText = String(command || '');
+    if (!shellWriteHit(cmdText)) return { block: false, cls: 'shell-read' };
+    // The owner-authorized publication exception is reachable only for a command
+    // that parses as ONE strictly-validated git commit/push; every other shell
+    // write keeps the conservative block.
+    let pub = null;
+    if (/(?:^|[;&|\n\s])git\s+(?:commit|push)\b/.test(cmdText)) {
+      const segs = splitShellSegments(cmdText);
+      if (segs.length === 1) pub = parseGitPublication(segs[0]);
+    }
+    if (pub) {
+      const why = await ownerGitPublishDenial(pub);
+      if (!why) {
+        await auditCreateDecision({ phase: intent, source: 'owner-turn', decision: 'allow', cls: 'owner-git-publish', op: pub.op });
+        return { block: false, cls: 'owner-git-publish' };
+      }
+      return {
+        block: true,
+        cls: 'shell-write',
+        reason: `handoff-create is planning-only: this git ${pub.op} was not allowed — ${why}. The exception needs an explicit owner message in this session plus a pure "git commit"/"git push" of docs-only files. Use Write/Edit for allowed docs/tests paths, or run /ukit:handoff-fullstack (or start a new session) to change source.`,
+      };
+    }
     return {
       block: true,
       cls: 'shell-write',
@@ -738,6 +1183,19 @@ async function createScopeGate() {
   }
 
   if (isAgent) {
+    // Planning dispatches run in THIS checkout: any isolation request (worktree/remote,
+    // native `isolation` string or `isolated: true`) is refused. Explicit none/false is fine.
+    const isoTasks = Array.isArray(input?.tasks) && input.tasks.length ? input.tasks : [input];
+    const isolated = isoTasks.some((t) => {
+      if (!t || typeof t !== 'object') return false;
+      const iso = t.isolation;
+      const isoOn = Boolean(iso) && !['none', 'false', 'off'].includes(String(iso).trim().toLowerCase());
+      return isoOn || t.isolated === true || String(t.isolated ?? '').toLowerCase() === 'true';
+    });
+    if (isolated) {
+      await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: 'agent-isolation' });
+      block('handoff-create is planning-only: planning dispatches run in this checkout and must omit the isolation field (no worktree/remote). Re-dispatch the same agent without `isolation`; do not change the agent.');
+    }
     const type = delegatedAgentTypes(input).find((t) => !CREATE_AGENT_ALLOW.has(t));
     if (type !== undefined) {
       await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: 'agent-delegation', agent: type || 'unspecified' });