mainflow 0.43.0-alpha.4 → 0.44.0-alpha.1

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { P as UNTIL_FORMS, X as parseUntil, Y as parseRef, Z as refExample, ct as stampMs, it as untilProblem, n as CLOSED_STATUS } from "./dist-D5rZ0MQH.js";
-import { $t as WriteError, At as MAINLINE_FILE, Bt as registeredName, Gt as nodeStorage, Ht as resolveHub, It as listHubs, Lt as notRegisteredMessage, Mt as requireSlug, Nt as hubAtRoot, O as loadSessions, Pt as hubHoldingFile, Q as HubError, Qt as DATA_DIR, Rt as readRegistry, S as sessionBriefing, Ut as unregisterHub, Vt as registryFile, Wt as userDataDir, X as applyOperation, Yt as realPath, Z as checkHubName, _t as MAX_FILE_BYTES, at as memberOfGroup, b as untilState, ct as unavailableHubs, d as migrateHubData, et as loadHub, f as migrateHub, g as RETRY_RULES, gt as MAX_CHANGE_PAGE, h as receiverFromEnv, jt as TASK_FILE, k as readSession, m as retroReportFromReceiver, mt as BLOB_HASH, p as retroReport, qt as dataFile, st as remoteMembers, tt as sectionText, u as groupPlan, ut as nowMinute, x as duplicateClaimLines, y as initHub, zt as registerHub } from "./host-BJvqZy-i.js";
+import { P as UNTIL_FORMS, X as parseUntil, Y as parseRef, Z as refExample, ct as stampMs, it as untilProblem, n as CLOSED_STATUS } from "./dist-CXrUfRQp.js";
+import { $t as realPath, Bt as notRegisteredMessage, Ft as requireSlug, Gt as resolveHub, Ht as registerHub, It as hubAtRoot, Jt as nodeStorage, Kt as unregisterHub, Lt as hubHoldingFile, Mt as MAINLINE_FILE, O as loadSessions, Pt as TASK_FILE, Q as HubError, S as sessionBriefing, Ut as registeredName, Vt as readRegistry, Wt as registryFile, X as applyOperation, Xt as dataFile, Z as checkHubName, b as untilState, d as migrateHubData, f as migrateHub, ft as nowMinute, g as RETRY_RULES, gt as BLOB_HASH, h as receiverFromEnv, k as readSession, lt as remoteMembers, m as retroReportFromReceiver, nn as DATA_DIR, p as retroReport, qt as userDataDir, rn as WriteError, rt as sectionText, st as memberOfGroup, tt as loadHub, u as groupPlan, ut as unavailableHubs, vt as MAX_CHANGE_PAGE, x as duplicateClaimLines, y as initHub, yt as MAX_FILE_BYTES, zt as listHubs } from "./host-C74j2Qox.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
-import { A as hubName, C as readRemote, D as Unreachable, E as ServerError, F as syncPaths, M as SETTINGS_FILE, O as ENV, T as ServerApi, _ as DaemonUnavailable, a as versionGate, b as readDaemon, c as oversizedFiles, d as planAnnounce, f as planFetch, g as DaemonRunning, h as startDaemon, i as requireWritableVersion, j as syncSettings, k as earlierToken, l as fetchDenial, m as toolCallOf, n as hubWriter, o as queuedCount, p as planFlush, r as writtenLines, s as remoteMode, t as CONFIRM_MS, u as hookAnswer, v as callDaemon, w as HubRewritingError, x as silentHint, y as probeDaemon } from "./operation-BhBbGauo.js";
+import { A as hubName, C as readRemote, D as Unreachable, E as ServerError, F as syncPaths, M as SETTINGS_FILE, O as ENV, T as ServerApi, _ as DaemonUnavailable, a as versionGate, b as readDaemon, c as oversizedFiles, d as planAnnounce, f as planFetch, g as DaemonRunning, h as startDaemon, i as requireWritableVersion, j as syncSettings, k as earlierToken, l as fetchDenial, m as toolCallOf, n as hubWriter, o as queuedCount, p as planFlush, r as writtenLines, s as remoteMode, t as CONFIRM_MS, u as hookAnswer, v as callDaemon, w as HubRewritingError, x as silentHint, y as probeDaemon } from "./operation-BmCeGKHw.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
 import { t as CLI_VERSION } from "./version-Dvv4jwF1.js";
 import { hookFallback, parsePayload, runHook } from "./hooks.js";
+import { runGrantCheck } from "./grant-check.js";
 import { exitCodeFor, launchUi, networkProbe, readUiRecord, startUiInBackground, watchHubGone } from "./launch.js";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
@@ -747,12 +748,12 @@ function window(s) {
 	if (scope.rule === "time") return `${stretches(s)}（對話紀錄沒有 mainflow 的輪次標頭，依行動時段）`;
 	const notes = joined([
 		scope.inferred > 0 && `${scope.inferred} 輪開始時沒有進行中的行動，依這輪開始或接手的行動${scope.inferredCost !== void 0 ? `（對話紀錄 ${usd(scope.inferredCost)}）` : ""}`,
-		scope.inherited > 0 && `${scope.inherited} 輪沒有標頭，沿用前一輪或派出子代理的那一輪`,
+		scope.inherited > 0 && `${scope.inherited} 輪沒有標頭，沿用最近的標頭寫的行動、前一輪或派出子代理的那一輪`,
 		scope.shared > 0 && `${scope.shared} 輪的行動也服務別條主脈絡，只算給第一個參照`,
 		scope.switched > 0 && `${scope.switched} 輪中途開始了別條主脈絡的行動，整輪仍算在這裡`,
 		scope.beforeHeads > 0 && `標頭出現前的 ${scope.beforeHeads} 輪依行動時段`
 	]);
-	return `${int(scope.counted)} / ${int(scope.turns)} 輪（依每輪的 mainflow 標頭${notes ? `；${notes}` : ""}）`;
+	return `${int(scope.counted)} / ${int(scope.turns)} 輪（依輪次的 mainflow 標頭${notes ? `；${notes}` : ""}）`;
 }
 function nodeLine(n) {
 	const cost = joined([
@@ -1637,6 +1638,7 @@ const RUNS = {
 			return 0;
 		});
 	},
+	"grant check": ({ cwd, opts }) => runGrantCheck(cwd, opts["dry-run"] ?? false),
 	"task show": ({ dirs, args }) => {
 		const { mainline, task } = findTask(loadHub(dirs), args[0]);
 		console.log(`${mainline.id}/${task.id}  ${task.status.padEnd(8)}  ${task.kind}  ${task.title}`);

package/dist/{dist-D5rZ0MQH.js → dist-CXrUfRQp.js}

@@ -123,22 +123,32 @@ function parseGrantTarget(action, target) {
 }
 /** The repository a target names, for the actions that name one. */
 const grantRepo = (target) => "repo" in target ? target.repo : void 0;
-/** Whether a grant's target covers the request. Only the actions a hook can resolve have requests. */
+/** Whether a grant's target covers the request. Only the actions a hook or grant check can resolve have requests. */
 function grantCovers(target, request) {
 	if (target.action !== request.action) return false;
 	if (target.action === "publish" && request.action === "publish") return target.name === request.name && satisfies(request.version, target.range);
 	if (target.action === "release" && request.action === "release") return request.repos.includes(target.repo) && globMatch(target.tag, request.tag);
+	if (target.action === "install-prompts" && request.action === "install-prompts") return target.unit === request.unit;
+	if ((target.action === "commit" || target.action === "push" || target.action === "merge-pr") && (request.action === "commit" || request.action === "push" || request.action === "merge-pr")) {
+		if (!request.repos.includes(target.repo)) return false;
+		return target.branch === void 0 || request.branch !== null && globMatch(target.branch, request.branch);
+	}
 	return false;
 }
 /**
-* The one way each hook-enforced action may be written for a grant to allow it; the hook asks for any other
-* writing, since what a free-form shell call publishes cannot be predicted reliably.
+* The one way each action may be written for a grant to allow it; any other writing is not judged, since what a
+* free-form shell call does cannot be predicted reliably. The PreToolUse hook allows publish and release in these
+* forms; `mainflow grant check` allows all six.
 */
 const GRANT_FORMS = {
+	commit: "單獨執行 `git commit …` 或 `git -C <目錄> commit …`，目錄或 cwd 要在 config.yaml 登記的倉庫或它的 worktree 裡",
+	push: "單獨執行 `git push [origin] [<分支>]`，可加 `-C <目錄>`、`-u` 或 `--set-upstream`，不帶分支時推目前分支；強制、刪除、`--mirror`、`--all`、`--tags` 與含 `:` 或 `+` 的 refspec 都不放行",
+	"merge-pr": "單獨執行 `gh pr merge [<編號>] [--squash|--merge|--rebase] [-R <owner/repo>]`，分支取 PR 的 base；帶 `--admin`、`-d`、`--delete-branch` 不放行",
 	publish: "在套件目錄單獨執行 `pnpm publish --ignore-scripts` 或 `npm publish --ignore-scripts`（可加 --access public|restricted、--tag <名稱>、--dry-run、--provenance，pnpm 另可加 --no-git-checks）",
-	release: "單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）"
+	release: "單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）",
+	"install-prompts": "單獨執行 `pnpm install:prompts`、`pnpm exec promptex build --install [<目錄>]` 或 `promptex build --install [<目錄>]`（可加 --unit <單元>），這次安裝的每個單元都要有授權；帶 --dry-run 不需授權"
 };
-/** The fixed form a grant allows, filled in with its target; undefined for actions the hook does not allow. */
+/** The fixed form the PreToolUse hook allows for a grant, filled in with its target; undefined for actions the hook does not allow. */
 function grantForm(target) {
 	if (target.action === "publish") return `在 ${target.name} 的套件目錄單獨執行 \`pnpm publish --ignore-scripts\` 或 \`npm publish --ignore-scripts\``;
 	if (target.action === "release") return `單獨執行 \`gh release create <符合 ${target.tag} 的 tag> -R <${target.repo} 的 GitHub owner/repo>\``;
@@ -147,9 +157,70 @@ function grantForm(target) {
 const DESCRIBED = 200;
 /** One line naming a request, for reasons and the ops log. */
 function describeRequest(request) {
-	const text = request.action === "publish" ? `publish ${request.name}@${request.version}` : `release ${request.repos.join("/") || "(unknown repo)"}@${request.tag}`;
+	const text = (() => {
+		switch (request.action) {
+			case "publish": return `publish ${request.name}@${request.version}`;
+			case "release": return `release ${request.repos.join("/") || "(unknown repo)"}@${request.tag}`;
+			case "install-prompts": return `install-prompts ${request.unit}`;
+			default: return `${request.action} ${request.repos.join("/") || "(unknown repo)"}${request.branch === null ? "（detached HEAD）" : `:${request.branch}`}`;
+		}
+	})();
 	return text.length > DESCRIBED ? `${text.slice(0, DESCRIBED)}…` : text;
 }
+/**
+* What is wrong with a paths glob, or null when it is one this CLI reads: relative to the hub root, names joined by
+* `/`, `*` and `?` inside a name, `**` as a whole name for any number of names, `..` only at the start to reach a
+* sibling of the hub, `.` alone for the hub root.
+*/
+function pathPatternProblem(pattern) {
+	if (pattern === ".") return null;
+	if (pattern === "") return "a path pattern cannot be empty";
+	if (pattern.startsWith("/") || pattern.startsWith("~")) return `"${pattern}" is not relative to the hub root`;
+	if (/[\\[\]{}!]/.test(pattern) || hasControl(pattern)) return `"${pattern}" uses a character this CLI does not read in a path pattern (\\, [, ], {, }, ! or a control character); write names with *, ? and **`;
+	const names = pattern.split("/");
+	if (names.some((name) => name === "" || name === ".")) return `"${pattern}" has an empty name or a "." inside it; write it without a trailing, leading or doubled /`;
+	const firstOther = names.findIndex((name) => name !== "..");
+	if (firstOther === -1) return `"${pattern}" names only directories above the hub root`;
+	if (names.slice(firstOther).includes("..")) return `"${pattern}" has ".." after a name; ".." may only lead the pattern`;
+	if (names.some((name) => name.includes("**") && name !== "**")) return `"${pattern}" has ** inside a name; ** stands alone for any number of names`;
+	return null;
+}
+/** Whether text holds a control character: below space, or DEL. */
+const hasControl = (text) => [...text].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127);
+/** Whether one name matches a pattern name; wildcards never match "." or "..". */
+function nameMatch(pattern, name) {
+	if (pattern === name) return true;
+	if (name === "." || name === "..") return false;
+	const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+	return new RegExp(`^${source}$`).test(name);
+}
+function namesMatch(pattern, names) {
+	if (pattern.length === 0) return names.length === 0;
+	const [head, ...rest] = pattern;
+	if (head === "**") {
+		for (let skip = 0; skip <= names.length; skip++) {
+			if (names.slice(0, skip).some((n) => n === "..")) break;
+			if (namesMatch(rest, names.slice(skip))) return true;
+		}
+		return false;
+	}
+	return names.length > 0 && nameMatch(head, names[0]) && namesMatch(rest, names.slice(1));
+}
+/**
+* Whether `path`, relative to the hub root with `/` between names ("" for the root), lies in a directory one of
+* the patterns matches: the path itself or a directory above it matches.
+*/
+function pathInPatterns(patterns, path) {
+	const names = path === "" || path === "." ? [] : path.split("/");
+	const ups = names.findIndex((name) => name !== "..");
+	if (ups === -1 && names.length > 0) return false;
+	const shortest = ups > 0 ? ups + 1 : 0;
+	return patterns.some((pattern) => {
+		const wanted = pattern === "." ? [] : pattern.split("/");
+		for (let k = shortest; k <= names.length; k++) if (namesMatch(wanted, names.slice(0, k))) return true;
+		return false;
+	});
+}
 /** Whether `text` matches a pattern where `*` is any run of characters and `?` one character, neither crossing `/`. */
 function globMatch(pattern, text) {
 	const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
@@ -821,13 +892,41 @@ const costSchema = z.object({
 /**
 * One thing a mainline or a group authorizes ahead of time: an action plus the target it covers. It applies only while
 * a session's action in progress serves this mainline (or a mainline of this group, or the group's own criterion)
-* and the mainline or group is still open.
+* and the mainline or group is still open, and, when it has a scope, while every limit the scope names holds.
 */
 const grantSchema = z.object({
 	id: id("grant"),
 	action: z.enum(GRANT_ACTIONS),
 	target: text,
-	note: text.optional()
+	note: text.optional(),
+	/**
+	* Limits beyond the mainline or group, all of which must hold: a task of the mainline the action serves, a session,
+	* paths of the hub the call's directory lies in. Unknown keys are refused, since a misspelt one would widen the grant.
+	*/
+	scope: z.strictObject({
+		task: id("task").optional(),
+		session: z.string().min(1).optional(),
+		paths: z.array(z.string()).min(1).optional()
+	}).superRefine((scope, ctx) => {
+		if (scope.task === void 0 && scope.session === void 0 && scope.paths === void 0) ctx.addIssue({
+			code: "custom",
+			path: [],
+			message: "scope names no limit; write task, session or paths, or leave scope out"
+		});
+		if (scope.session !== void 0 && !SESSION_ID.test(scope.session)) ctx.addIssue({
+			code: "custom",
+			path: ["session"],
+			message: `"${scope.session}" is not a session id, e.g. claude-code-1a2b3c4d`
+		});
+		scope.paths?.forEach((pattern, i) => {
+			const problem = pathPatternProblem(pattern);
+			if (problem) ctx.addIssue({
+				code: "custom",
+				path: ["paths", i],
+				message: problem
+			});
+		});
+	}).optional()
 }).superRefine((g, ctx) => {
 	const parsed = parseGrantTarget(g.action, g.target);
 	if (!parsed.ok) ctx.addIssue({
@@ -1066,8 +1165,10 @@ const sessionSchema = z.object({
 	description: text.optional(),
 	depth: z.number().int().nonnegative().optional(),
 	summary: text.optional(),
-	/** Digest of the grants, waits and queue warnings the last turn reminder listed in full, so an unchanged set is not listed again */
+	/** Digest of the whole turn reminder last sent, so the same reminder is not sent again */
 	reminderDigest: text.optional(),
+	/** Digests of the check problems the hook after a write last handed over, so a problem already reported is not reported again */
+	checkReported: z.array(text).optional(),
 	/** Hidden from the default views; independent of status, an ended session stays visible until archived */
 	archivedAt: date.optional()
 });
@@ -1158,4 +1259,4 @@ function parseOpsLine(line) {
 	return parsed.success ? parsed.data : null;
 }
 //#endregion
-export { removedUntil as $, SURVEY_LINES as A, groupSchema as B, PRIORITIES as C, SESSION_ID as D, SERVES_REF as E, WORK_STATUS as F, mainlineSchema as G, isMainflowRange as H, configSchema as I, parseOpsLine as J, opsEntrySchema as K, decisionSchema as L, TASK_REQUIRED_SECTIONS as M, TASK_SECTIONS as N, SESSION_STATUS as O, UNTIL_FORMS as P, refMainline as Q, findingSchema as R, MERGE_STATES as S, RESERVED_HUB_NAMES as T, issueSchema as U, hubRegistrySchema as V, listedRepos as W, parseUntil as X, parseRef as Y, refExample as Z, ISSUE_STATUS as _, DECISION_SECTIONS as a, waitingForAction as at, MAINLINE_SECTIONS as b, FINDING_SECTIONS as c, stampMs as ct, GROUP_SECTIONS as d, GRANT_TARGET_FORMS as dt, repoPath as et, GROUP_STATUS as f, describeRequest as ft, ISSUE_SECTIONS as g, parseGrantTarget as gt, ID_PATTERNS as h, grantRepo as ht, DECISION_BASES as i, untilProblem as it, SURVEY_SECTION as j, SLUG as k, FINDING_STATUS as l, GRANT_ACTIONS as lt, HUB_NAME as m, grantForm as mt, CLOSED_STATUS as n, sessionSchema as nt, DECISION_STATUS as o, waitingForRef as ot, GROUP_SUMMARY_SECTION as p, grantCovers as pt, parseActionRef as q, DECIDERS as r, taskSchema as rt, DEFAULT_CATEGORIES as s, OFFSET as st, CHECKLIST_REF as t, repoPaths as tt, FORMAT_VERSION as u, GRANT_FORMS as ut, LINK_RELS as v, REF_EXAMPLES as w, MAINLINE_STATUS as x, MAINFLOW_RANGE as y, formatOpsEntry as z };
+export { removedUntil as $, SURVEY_LINES as A, groupSchema as B, PRIORITIES as C, SESSION_ID as D, SERVES_REF as E, WORK_STATUS as F, mainlineSchema as G, isMainflowRange as H, configSchema as I, parseOpsLine as J, opsEntrySchema as K, decisionSchema as L, TASK_REQUIRED_SECTIONS as M, TASK_SECTIONS as N, SESSION_STATUS as O, UNTIL_FORMS as P, refMainline as Q, findingSchema as R, MERGE_STATES as S, RESERVED_HUB_NAMES as T, issueSchema as U, hubRegistrySchema as V, listedRepos as W, parseUntil as X, parseRef as Y, refExample as Z, ISSUE_STATUS as _, parseGrantTarget as _t, DECISION_SECTIONS as a, waitingForAction as at, MAINLINE_SECTIONS as b, FINDING_SECTIONS as c, stampMs as ct, GROUP_SECTIONS as d, GRANT_TARGET_FORMS as dt, repoPath as et, GROUP_STATUS as f, describeRequest as ft, ISSUE_SECTIONS as g, hasControl as gt, ID_PATTERNS as h, grantRepo as ht, DECISION_BASES as i, untilProblem as it, SURVEY_SECTION as j, SLUG as k, FINDING_STATUS as l, GRANT_ACTIONS as lt, HUB_NAME as m, grantForm as mt, CLOSED_STATUS as n, sessionSchema as nt, DECISION_STATUS as o, waitingForRef as ot, GROUP_SUMMARY_SECTION as p, grantCovers as pt, parseActionRef as q, DECIDERS as r, taskSchema as rt, DEFAULT_CATEGORIES as s, OFFSET as st, CHECKLIST_REF as t, repoPaths as tt, FORMAT_VERSION as u, GRANT_FORMS as ut, LINK_RELS as v, pathInPatterns as vt, REF_EXAMPLES as w, MAINLINE_STATUS as x, MAINFLOW_RANGE as y, formatOpsEntry as z };

package/dist/facts.d.ts

@@ -1,4 +1,4 @@
-import { g as SurveyLine, l as ID_PATTERNS, m as SLUG, o as FORMAT_VERSION, p as SERVES_REF, r as CHECKLIST_REF, v as Until } from "./index-BqPQp6TF.js";
+import { g as SurveyLine, l as ID_PATTERNS, m as SLUG, o as FORMAT_VERSION, p as SERVES_REF, r as CHECKLIST_REF, v as Until } from "./index-l8QUG80k.js";
 //#region src/facts.d.ts
 export interface CommandSpec {
   usage: string;
@@ -153,6 +153,12 @@ export declare const COMMAND_SPECS: {
     readonly args: 2;
     readonly needsHub: false;
   };
+  readonly 'grant check': {
+    readonly usage: 'grant check [--dry-run]';
+    readonly summary: 'Judge whether a grant covers one tool call read from stdin as {"tool","input","cwd","sessionId"} (the shape of a Claude Code mod tool.check event) and print {"decision":"allow"|"none","reason","grant"}. Only a single Bash command in a fixed form (GRANTS.forms) can be allowed; anything else, or anything that cannot be read, is none. An allow is logged to the ops log unless --dry-run. Always exits 0';
+    readonly args: 0;
+    readonly needsHub: false;
+  };
   readonly 'new mainline': {
     readonly usage: 'new mainline <slug> --title <title> [--group <w>] [--priority P0|P1|P2|P3]';
     readonly summary: 'Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group, or in one of another registered hub as {hub}:w001';
@@ -694,9 +700,10 @@ export declare const LINKS: {
  * What a mainline's or group's grants authorize: each action with the form of its target. A mainline's grant applies
  * only while the session's action in progress serves the mainline and the mainline is active or planning. A group's
  * grant applies while the group is open and the action serves one of the group's mainlines (of this hub) or the
- * group's own criterion. The PreToolUse hook
- * allows `publish` and `release` only when the command is written in the fixed form in `forms`; the other
- * actions are for the executor to read.
+ * group's own criterion. A grant's optional `scope` narrows it further (`scope`). The PreToolUse hook allows
+ * `publish` and `release` only when the command is written in the fixed form in `forms`; `mainflow grant check`
+ * judges every action in `judgedByGrantCheck` the same way. sync-hubs has no single-command form and is for the
+ * executor to read.
  */
 export declare const GRANTS: {
   readonly actions: readonly ["commit", "push", "merge-pr", "publish", "release", "install-prompts", "sync-hubs"];
@@ -705,9 +712,19 @@ export declare const GRANTS: {
     example: string;
   }>;
   readonly enforcedByHook: readonly ['publish', 'release'];
+  readonly judgedByGrantCheck: readonly ['commit', 'push', 'merge-pr', 'publish', 'release', 'install-prompts'];
   readonly forms: {
+    readonly commit: '單獨執行 `git commit …` 或 `git -C <目錄> commit …`，目錄或 cwd 要在 config.yaml 登記的倉庫或它的 worktree 裡';
+    readonly push: '單獨執行 `git push [origin] [<分支>]`，可加 `-C <目錄>`、`-u` 或 `--set-upstream`，不帶分支時推目前分支；強制、刪除、`--mirror`、`--all`、`--tags` 與含 `:` 或 `+` 的 refspec 都不放行';
+    readonly 'merge-pr': '單獨執行 `gh pr merge [<編號>] [--squash|--merge|--rebase] [-R <owner/repo>]`，分支取 PR 的 base；帶 `--admin`、`-d`、`--delete-branch` 不放行';
     readonly publish: '在套件目錄單獨執行 `pnpm publish --ignore-scripts` 或 `npm publish --ignore-scripts`（可加 --access public|restricted、--tag <名稱>、--dry-run、--provenance，pnpm 另可加 --no-git-checks）';
     readonly release: '單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）';
+    readonly 'install-prompts': '單獨執行 `pnpm install:prompts`、`pnpm exec promptex build --install [<目錄>]` 或 `promptex build --install [<目錄>]`（可加 --unit <單元>），這次安裝的每個單元都要有授權；帶 --dry-run 不需授權';
+  };
+  readonly scope: {
+    readonly task: '任務編號 t{NNN}，屬於授權所在的主脈絡；目前行動要服務這個任務的 checklist 項目。組的授權不能寫';
+    readonly session: 'mainflow 會話 id，例如 claude-code-1a2b3c4d；只有這場會話的呼叫適用';
+    readonly paths: '相對 hub 根目錄的 glob 清單；指令的工作目錄（git 的 -C、promptex 的目錄）要落在其中一個符合的目錄裡。* 與 ? 不跨 /，** 是任意幾層，.. 只能寫在開頭，. 代表 hub 根目錄';
   };
 };
 /**
@@ -775,7 +792,7 @@ export declare const FIELDS: {
   readonly group: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec];
   readonly criterion: FieldSpec[];
   readonly checklistItem: readonly [...FieldSpec[], FieldSpec];
-  readonly grant: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec];
+  readonly grant: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly action: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly link: readonly [FieldSpec, FieldSpec, FieldSpec];
 };

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { A as SURVEY_LINES, C as PRIORITIES, E as SERVES_REF, F as WORK_STATUS, M as TASK_REQUIRED_SECTIONS, N as TASK_SECTIONS, O as SESSION_STATUS, P as UNTIL_FORMS, S as MERGE_STATES, _ as ISSUE_STATUS, a as DECISION_SECTIONS, b as MAINLINE_SECTIONS, c as FINDING_SECTIONS, d as GROUP_SECTIONS, dt as GRANT_TARGET_FORMS, f as GROUP_STATUS, g as ISSUE_SECTIONS, h as ID_PATTERNS, i as DECISION_BASES, j as SURVEY_SECTION, k as SLUG, l as FINDING_STATUS, lt as GRANT_ACTIONS, n as CLOSED_STATUS, o as DECISION_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, ut as GRANT_FORMS, v as LINK_RELS, x as MAINLINE_STATUS } from "./dist-D5rZ0MQH.js";
+import { A as SURVEY_LINES, C as PRIORITIES, E as SERVES_REF, F as WORK_STATUS, M as TASK_REQUIRED_SECTIONS, N as TASK_SECTIONS, O as SESSION_STATUS, P as UNTIL_FORMS, S as MERGE_STATES, _ as ISSUE_STATUS, a as DECISION_SECTIONS, b as MAINLINE_SECTIONS, c as FINDING_SECTIONS, d as GROUP_SECTIONS, dt as GRANT_TARGET_FORMS, f as GROUP_STATUS, g as ISSUE_SECTIONS, h as ID_PATTERNS, i as DECISION_BASES, j as SURVEY_SECTION, k as SLUG, l as FINDING_STATUS, lt as GRANT_ACTIONS, n as CLOSED_STATUS, o as DECISION_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, ut as GRANT_FORMS, v as LINK_RELS, x as MAINLINE_STATUS } from "./dist-CXrUfRQp.js";
 import { a as LABEL_ROLES, i as FINDING_SEVERITIES, n as FINDING_CLASSES, r as FINDING_FIELDS, t as FINDINGS_FENCE } from "./retro-formats-ECy0gGOL.js";
 //#region src/facts.ts
 const COMMAND_SPECS = {
@@ -143,6 +143,12 @@ const COMMAND_SPECS = {
 		args: 2,
 		needsHub: false
 	},
+	"grant check": {
+		usage: "grant check [--dry-run]",
+		summary: "Judge whether a grant covers one tool call read from stdin as {\"tool\",\"input\",\"cwd\",\"sessionId\"} (the shape of a Claude Code mod tool.check event) and print {\"decision\":\"allow\"|\"none\",\"reason\",\"grant\"}. Only a single Bash command in a fixed form (GRANTS.forms) can be allowed; anything else, or anything that cannot be read, is none. An allow is logged to the ops log unless --dry-run. Always exits 0",
+		args: 0,
+		needsHub: false
+	},
 	"new mainline": {
 		usage: "new mainline <slug> --title <title> [--group <w>] [--priority P0|P1|P2|P3]",
 		summary: "Create mainline.md with the next id and the section template; write the rest in the file. --group puts it in an existing group, or in one of another registered hub as {hub}:w001",
@@ -603,15 +609,29 @@ const LINKS = { rels: LINK_RELS };
 * What a mainline's or group's grants authorize: each action with the form of its target. A mainline's grant applies
 * only while the session's action in progress serves the mainline and the mainline is active or planning. A group's
 * grant applies while the group is open and the action serves one of the group's mainlines (of this hub) or the
-* group's own criterion. The PreToolUse hook
-* allows `publish` and `release` only when the command is written in the fixed form in `forms`; the other
-* actions are for the executor to read.
+* group's own criterion. A grant's optional `scope` narrows it further (`scope`). The PreToolUse hook allows
+* `publish` and `release` only when the command is written in the fixed form in `forms`; `mainflow grant check`
+* judges every action in `judgedByGrantCheck` the same way. sync-hubs has no single-command form and is for the
+* executor to read.
 */
 const GRANTS = {
 	actions: GRANT_ACTIONS,
 	targets: GRANT_TARGET_FORMS,
 	enforcedByHook: ["publish", "release"],
-	forms: GRANT_FORMS
+	judgedByGrantCheck: [
+		"commit",
+		"push",
+		"merge-pr",
+		"publish",
+		"release",
+		"install-prompts"
+	],
+	forms: GRANT_FORMS,
+	scope: {
+		task: "任務編號 t{NNN}，屬於授權所在的主脈絡；目前行動要服務這個任務的 checklist 項目。組的授權不能寫",
+		session: "mainflow 會話 id，例如 claude-code-1a2b3c4d；只有這場會話的呼叫適用",
+		paths: "相對 hub 根目錄的 glob 清單；指令的工作目錄（git 的 -C、promptex 的目錄）要落在其中一個符合的目錄裡。* 與 ? 不跨 /，** 是任意幾層，.. 只能寫在開頭，. 代表 hub 根目錄"
+	}
 };
 /**
 * Where each kind of entry lives in the hub's data directory, written as messages name a file of the hub: `.mainflow/`
@@ -765,7 +785,8 @@ const FIELDS = {
 		field("id", true, "清單內不重複的編號 g{NNN}"),
 		field("action", true, "授權的動作：commit、push、merge-pr、publish、release、install-prompts、sync-hubs"),
 		field("target", true, "授權的目標，格式依動作而定，見 GRANTS.targets；倉庫名稱需在 config.yaml 登記"),
-		field("note", false, "一句話說明")
+		field("note", false, "一句話說明"),
+		field("scope", false, "再收窄的範圍，欄位 task、session、paths 見 GRANTS.scope；寫了的欄位全部成立才生效，沒寫時照主脈絡或組的生效條件")
 	],
 	action: [
 		field("id", true, "會話內不重複的編號 a{NNN}，由 action add 配發"),
@@ -778,7 +799,7 @@ const FIELDS = {
 		field("doneAt", false, "轉為 done 或 dropped 時由 CLI 寫入")
 	],
 	link: [
-		field("rel", true, "關係類型：depends-on、relates、split-from，反向由讀者推出"),
+		field("rel", true, "關係類型：depends-on 表示要等對方完成才能推進，主脈絡記的才畫成主脈絡之間的線；relates 表示相關，含沿用對方的產物或知識出處；split-from 表示從對方拆出；反向由讀者推出"),
 		field("to", true, "對方的參照，不能在同一條主脈絡內，也可以是組 w{NNN}；其他 hub 的加 {hub}: 前綴"),
 		field("note", false, "一句話說明這個關係")
 	]

package/dist/grant-check.d.ts

@@ -0,0 +1,45 @@
+import { o as HubDirs } from "./index-jq7lN8V8.js";
+import { t as HubWrite } from "./operation-BroV98VB.js";
+//#region src/grant-check.d.ts
+/** What grant check prints. `grants` lists every grant used when more than one was, as for an install of several units. */
+export interface GrantVerdict {
+  decision: 'allow' | 'none';
+  reason: string;
+  grant?: string;
+  grants?: string[];
+}
+/** The base branch of a pull request, as `gh pr view [<number>] [-R <repo>] --json baseRefName` in `cwd` gives it; null when it cannot be read. */
+export type PrBase = (query: {
+  cwd: string;
+  number?: string;
+  repo?: string;
+}) => string | null;
+/** The units `command args` in `cwd` would install, read from promptex's dry run; null when they cannot be read. */
+export type ListUnits = (run: {
+  command: string;
+  args: string[];
+  cwd: string;
+}) => string[] | null;
+export interface GrantCheckContext {
+  /** The session's hub; null outside any */
+  dirs: HubDirs | null;
+  /** The writer for the ops log; the hub's writer, as a hook's, when left out */
+  write?: HubWrite;
+  /** Judge without writing the ops log */
+  dryRun?: boolean;
+  env?: NodeJS.ProcessEnv;
+  /** Lines for stderr, such as an ops log that could not be written */
+  warn?: (message: string) => void;
+  prBase?: PrBase;
+  listUnits?: ListUnits;
+}
+/**
+ * Split one simple command into the words the shell passes on: words separated by spaces, each made of plain
+ * characters, single-quoted text, and double-quoted text in which the shell expands nothing. Anything else throws.
+ */
+export declare function shellWords(command: string): string[];
+/** Judge one call; any failure is `none`, so a caller that cannot be told otherwise keeps its own decision. */
+export declare function grantCheck(input: unknown, ctx: GrantCheckContext): Promise<GrantVerdict>;
+/** `mainflow grant check`: read the call from stdin, print the verdict as one JSON line, exit 0. */
+export declare function runGrantCheck(cwd: string, dryRun: boolean): Promise<number>;
+//#endregion