@attalabs/vinaya 0.17.1 → 0.18.0

package/README.md

@@ -20,7 +20,7 @@ npx @attalabs/vinaya init        # or: pnpm dlx / yarn dlx / bunx
 | `vinaya check <name> \| --all` | Run one check, or every registered check (core + `vinaya.config.json`-registered). `--json` for the enveloped `{ checks: CheckOutcome[] }` form; `--diff-only` scopes `scope: 'diff'` checks to changed files; `--parallel[=n]` caps concurrency (default: cpu-derived). Findings always print as the check contract's JSON lines on stderr, regardless of `--json`. Exit 0 iff every check passed. |
 | `vinaya new check <yourname>/<id>` | Scaffold a self-contained custom check into `./scripts/vinaya-checks/<id>.ts`, ready to register in `vinaya.config.json` under that namespaced key |
 | `vinaya review post --role code-reviewer \| security --pr <n> ...` | Render, post, and self-verify a code-reviewer or security-review verdict comment on a PR from structured flags (verdict, findings, per-field text) instead of a hand-typed comment. Resolves the PR's real head itself (`gh pr view --json headRefOid`); renders every structural `VERDICT:`/`Judged head:` line from validated inputs, never from caller-supplied text; refuses a contradictory verdict (a BLOCKER/CRITICAL-or-HIGH finding with a clean verdict) before posting anything; and after posting, re-fetches the comment and refuses to exit 0 unless it re-parses through the exact `extractCodeReviewVerdict`/`extractSecurityReviewVerdict` functions the merge gate calls. `--json` for the enveloped machine form. |
-| `vinaya studio` | Launch Vinaya Studio. Inside a checkout that carries Studio's source (`apps/vinaya-studio/web` — it lives in the attalabs monorepo, not this repository) it runs the dev app; a published install runs its bundled standalone server instead, fetched from attalabs' published release artifact at publish time. |
+| `vinaya studio` | Launch Vinaya Studio. Inside a checkout that carries Studio's source (`apps/vinaya-studio/web` — it lives in the attalabs monorepo, not this repository) it runs the dev app; a published install runs its bundled standalone server instead, fetched from attalabs' published release artifact at publish time. `--port <n>` binds an exact port — see below. |
 
 ## Config
 
@@ -74,6 +74,8 @@ One thing git cannot version is the config itself: **each fresh clone runs `git
 
 Two shapes deviate: a repo already using **husky** keeps its `.husky/` directory (husky's `prepare` script owns per-clone wiring), and a repo with its own active raw hooks in `.git/hooks` stays on the legacy append-a-managed-block layout there — re-routing `core.hooksPath` would silently disable the adopter's own hooks. On that legacy layout `vinaya doctor` warns that clones have no hooks, and `vinaya upgrade` migrates to the tracked layout as soon as nothing foreign would be disabled.
 
+On that legacy `.git/hooks` layout, note where the hook actually lives: hooks are never per-worktree, so its real home is the main checkout's shared hooks directory (`git rev-parse --git-common-dir`), which from a linked worktree is outside that worktree's own root. `vinaya eject` follows the hook there and bounds the removal to that directory's `hooks/` subtree, rather than to the worktree root — so ejecting from a linked worktree strips the hook instead of leaving it armed. A canonically spelled block path resolving anywhere else is refused, and the refusal is whole-run: `eject` removes nothing at all rather than making a partial destructive pass. (The `.git/` test is byte-exact, so a non-canonical spelling takes the working-tree branch instead — nothing vinaya generates produces one.)
+
 ## Agent skills
 
 The emitter that will generate skill pointers under `.agents/skills/vinaya-<role>/SKILL.md`, for tools natively scanning `.agents/skills/` (Codex, Antigravity, Grok Build), is built — `vinaya init` does not call it yet. Each file, once wired, is a 3-line pointer delegating to `vinaya doctrine --role <role>` at read time. User-facing flag, `init`/`upgrade`/`eject`/`doctor` wiring, and the `--agents` selection flag land in #152.
@@ -136,6 +138,38 @@ The generated review-authority workflows run only default-branch code: the requi
 
 `.vinaya/doc-owners` binds code globs to the docs that must change with them; `vinaya check`'s C5 gate enforces that binding against each pull request's own diff — it fires only when a changed file matches a bound glob. That leaves a gap C5 cannot close on its own: a binding whose code was deleted or renamed wholesale matches nothing on any later diff, ever again, and reads as healthy forever. `vinaya doctor` closes it separately — it never fails `vinaya check` — by walking every binding against the repo's full tracked-file list and reporting any whose code glob matches zero tracked files anywhere in the repo, or whose in-repo doc pointer doesn't exist on disk. Report-only, like every other `vinaya doctor` diagnostic: it repoints or removes nothing itself.
 
+## Brief-schema divergence
+
+`briefSchema` in `vinaya.config.json` is yours: `vinaya upgrade` preserves it wholesale and never rewrites it. On its own that ownership has a silent cost — nothing else reads it either, so a builtin deleted to work around a defect stays deleted, with no later upgrade to repair it and nothing to surface it.
+
+`vinaya doctor` reports the divergence. It compares your `briefSchema.pr` and `briefSchema.issue` against the set `vinaya init` ships and names any builtin that is absent — nothing more. Extra sections, whether a second builtin or your own `heading`/`field`/`phrase` matcher, are additions rather than weakenings and are never reported. The finding is `info` severity and can never fail your CI: running without a builtin is legitimate configuration, and the goal is to make the choice visible, not to argue you back to the default.
+
+Once an omission is deliberate, name it in `briefSchema.ack` and it goes quiet:
+
+```json
+{ "briefSchema": { "ack": ["closesN"] } }
+```
+
+`ack` grants nothing and gates nothing — it only silences this report, and acking a builtin you still declare changes no behaviour anywhere. A deletion you did not intend, having no ack, keeps surfacing.
+
+Two things worth knowing about its shape. `ack` is one flat list rather than per-kind, so acking a name that the shipped default declares for **both** kinds — `project` is the only such name today — silences it for both. And a config carrying no `briefSchema` key at all diverges on every builtin, so it reports on every run until you either declare the sections or ack them; that is the one shape where this becomes standing output rather than a one-time notice.
+
+Report-only, like every other `vinaya doctor` diagnostic: it restores nothing itself.
+
+## Pinning Studio's port
+
+`vinaya studio` binds `3008`, or `3108` when that is taken. `--port <n>` overrides both, and the override does **not** fall back: if the port you named is busy, the command refuses instead of quietly binding a different one.
+
+That asymmetry is deliberate. The default pair exists so a casual `vinaya studio` still comes up when something else holds `3008`. But naming a port is how you buy certainty about which server answered you — and silently moving to another port spends exactly that. Run two Studio servers on one machine without it and a `200` from `/studio` tells you nothing about which process replied.
+
+```bash
+vinaya studio --port 3208     # or --port=3208
+```
+
+A malformed value exits `2` before anything starts: no value, a non-number, one outside `1`–`65535`, a leading zero, or the flag given twice with different values.
+
+The flag applies to a published install, where this CLI launches the bundled server and owns the port. In a checkout carrying Studio's source it is refused, because that path runs Studio's own dev script, which picks its own port and ignores what it is passed — accepting the flag there would report a port nothing ever binds.
+
 ## Known limits
 
 The five core AEG checks (`coherence`, `dispatch-readiness`, and siblings) are bound to the Vinaya development repository — they read governance documents relative to it. Outside a Vinaya workspace, `vinaya check --all` reports those checks as `status: 'error'` rather than crashing.

package/dist/checks/bin/check-body-bare-digits.js

@@ -3184,7 +3184,8 @@ var BriefSectionSchema = z.union([
 ]);
 var BriefSchemaSchema = z.object({
   pr: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
-  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional()
+  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
+  ack: z.array(z.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-coherence.js

@@ -3207,7 +3207,8 @@ var BriefSectionSchema = z2.union([
 ]);
 var BriefSchemaSchema = z2.object({
   pr: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
-  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional()
+  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
+  ack: z2.array(z2.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-dispatch-readiness.js

@@ -3205,7 +3205,8 @@ var BriefSectionSchema = z2.union([
 ]);
 var BriefSchemaSchema = z2.object({
   pr: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
-  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional()
+  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
+  ack: z2.array(z2.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-doc-coverage-push.js

@@ -3206,7 +3206,8 @@ var BriefSectionSchema = z.union([
 ]);
 var BriefSchemaSchema = z.object({
   pr: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
-  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional()
+  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
+  ack: z.array(z.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-doc-coverage.js

@@ -3206,7 +3206,8 @@ var BriefSectionSchema = z.union([
 ]);
 var BriefSchemaSchema = z.object({
   pr: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
-  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional()
+  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
+  ack: z.array(z.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-first-push-dispatch.js

@@ -3204,7 +3204,8 @@ var BriefSectionSchema = z2.union([
 ]);
 var BriefSchemaSchema = z2.object({
   pr: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
-  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional()
+  issue: z2.object({ sections: z2.array(BriefSectionSchema) }).optional(),
+  ack: z2.array(z2.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/checks/bin/check-review-gate.js

@@ -3190,7 +3190,8 @@ var BriefSectionSchema = z.union([
 ]);
 var BriefSchemaSchema = z.object({
   pr: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
-  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional()
+  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
+  ack: z.array(z.enum(BRIEF_BUILTINS)).optional()
 });
 function isSafeRepoRelPath(p) {
   if (p.length === 0)

package/dist/index.js

@@ -2025,18 +2025,6 @@ function buildInitOps(ctx) {
   ops.push({ kind: "print", message: CODEOWNERS_NOTE, group: "Branch protection (printed, never applied)" });
   return ops;
 }
-function buildInitProductOps(name) {
-  const safe = name.trim();
-  return [
-    {
-      kind: "create-label",
-      name: `project:${safe}`,
-      color: "0e8a16",
-      description: `Governed product area: ${safe}`,
-      group: `Governed product area: ${safe}`
-    }
-  ];
-}
 
 // src/lib/ops.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
@@ -2139,7 +2127,8 @@ var BriefSectionSchema = z.union([
 ]);
 var BriefSchemaSchema = z.object({
   pr: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
-  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional()
+  issue: z.object({ sections: z.array(BriefSectionSchema) }).optional(),
+  ack: z.array(z.enum(BRIEF_BUILTINS)).optional()
 });
 var MANAGED_MANIFEST_VERSION = 2;
 function isSafeRepoRelPath(p) {
@@ -2343,17 +2332,22 @@ ${end}`;
 function abs(repoRoot, relPath) {
   return join4(repoRoot, relPath);
 }
+var GIT_DIR_PREFIX = ".git/";
 function resolveManagedBlockPath(repoRoot, opPath) {
-  if (!opPath.startsWith(".git/"))
+  if (!opPath.startsWith(GIT_DIR_PREFIX))
     return join4(repoRoot, opPath);
+  return join4(gitCommonDir(repoRoot), opPath.slice(GIT_DIR_PREFIX.length));
+}
+function gitCommonDir(repoRoot) {
   try {
     const commonDir = execFileSync3("git", ["-C", repoRoot, "rev-parse", "--git-common-dir"], {
       encoding: "utf8"
     }).trim();
-    const gitDir = isAbsolute(commonDir) ? commonDir : join4(repoRoot, commonDir);
-    return join4(gitDir, opPath.slice(".git/".length));
+    if (commonDir === "")
+      return join4(repoRoot, ".git");
+    return isAbsolute(commonDir) ? commonDir : join4(repoRoot, commonDir);
   } catch {
-    return join4(repoRoot, opPath);
+    return join4(repoRoot, ".git");
   }
 }
 function containedAbs(repoRoot, relPath) {
@@ -2363,6 +2357,16 @@ function containedAbs(repoRoot, relPath) {
     return null;
   return target === root || target.startsWith(root + sep) ? target : null;
 }
+function containedManagedBlockAbs(repoRoot, relPath) {
+  if (!relPath.startsWith(GIT_DIR_PREFIX))
+    return containedAbs(repoRoot, relPath);
+  const commonDir = gitCommonDir(repoRoot);
+  const hooksRoot = resolve(join4(commonDir, "hooks"));
+  const target = resolve(join4(commonDir, relPath.slice(GIT_DIR_PREFIX.length)));
+  if (target === hooksRoot)
+    return null;
+  return target.startsWith(hooksRoot + sep) ? target : null;
+}
 function fileContains(repoRoot, relPath, needle) {
   const p = resolveManagedBlockPath(repoRoot, relPath);
   if (!existsSync3(p))
@@ -2583,7 +2587,7 @@ function planEject(manifest, repoRoot) {
   const actions = [];
   const escapes = [];
   for (const b of manifest.blocks) {
-    const p = containedAbs(repoRoot, b.path);
+    const p = containedManagedBlockAbs(repoRoot, b.path);
     if (p === null) {
       escapes.push(b.path);
       continue;
@@ -2648,7 +2652,7 @@ function applyEject(plan, repoRoot) {
     if (a.kind === "strip-block") {
       if (!a.present)
         continue;
-      const p = containedAbs(repoRoot, a.path);
+      const p = containedManagedBlockAbs(repoRoot, a.path);
       if (p === null)
         continue;
       const content = readFileSync3(p, "utf-8");
@@ -4735,6 +4739,31 @@ function diagnoseBlastRadiusDeprecation(repoRoot, config) {
     warn("blast-radius", `${LEGACY_AEG_PACKAGES_PATH} is deprecated — checkBlastRadiusScope now derives packages/* domains live and ships built-in cross-cutting defaults. Declare anything beyond those in vinaya.config.json's blastRadius.extraDomains instead. ${migrationNote}`)
   ];
 }
+var BRIEF_KIND_LABEL = {
+  pr: "PR bodies",
+  issue: "task Issue bodies"
+};
+function builtinsIn(sections) {
+  return (sections ?? []).flatMap((s) => ("builtin" in s) ? [s.builtin] : []);
+}
+function diagnoseBriefSchemaDrift(config) {
+  if (!config)
+    return [];
+  const shipped = starterConfig().briefSchema;
+  const acked = new Set(config.briefSchema?.ack ?? []);
+  const findings = [];
+  for (const kind of ["pr", "issue"]) {
+    const expected = builtinsIn(shipped?.[kind]?.sections);
+    if (expected.length === 0)
+      continue;
+    const present = new Set(builtinsIn(config.briefSchema?.[kind]?.sections));
+    const missing = expected.filter((b) => !present.has(b) && !acked.has(b));
+    if (missing.length === 0)
+      continue;
+    findings.push(info("brief-schema", `briefSchema.${kind} is missing ${missing.length} builtin${missing.length === 1 ? "" : "s"} the shipped default declares for ${BRIEF_KIND_LABEL[kind]}: ${missing.join(", ")}. ` + "This is adopter-owned config — `vinaya upgrade` will never restore it, and nothing else reports it. " + "If the omission is deliberate, list those names in `briefSchema.ack` to silence this; if it was a workaround for a vinaya defect, check whether that defect is fixed and the builtin can come back."));
+  }
+  return findings;
+}
 function diagnoseEnvDeclarations(repoRoot, config) {
   const resolved = resolveChecks(coreCheckRegistry(), config?.checks).resolved;
   const specs = resolved.map((entry2) => entry2.source === "config" ? { ...entry2.spec, run: join9(repoRoot, entry2.spec.run) } : entry2.spec);
@@ -4893,6 +4922,7 @@ async function runDoctor(args, deps) {
     findings.push(...diagnoseDocOwnersHealth(repo.repoRoot));
   }
   findings.push(...diagnoseBlastRadiusDeprecation(repo.repoRoot, configRead.kind === "ok" ? configRead.config : null));
+  findings.push(...diagnoseBriefSchemaDrift(configRead.kind === "ok" ? configRead.config : null));
   findings.push(...diagnoseEnvDeclarations(repo.repoRoot, configRead.kind === "ok" ? configRead.config : null));
   findings.push(...diagnoseCheckClassification(configRead.kind === "ok" ? configRead.config : null));
   findings.push(...diagnoseGlobalConfigChecks());
@@ -5034,7 +5064,7 @@ async function runEject(args, deps) {
   const plan = planEject(read.manifest, repo.repoRoot);
   const unarm = read.manifest.blocks.some((b) => b.path.startsWith(`${TRACKED_HOOK_DIR}/`)) && await deps.readHooksPath(repo.repoRoot) === TRACKED_HOOK_DIR;
   if (plan.escapes.length > 0) {
-    console.error("Error: the ownership manifest records paths that resolve OUTSIDE this repo:");
+    console.error("Error: the ownership manifest records paths that resolve OUTSIDE the bounds vinaya may touch:");
     for (const p of plan.escapes)
       console.error(`  ${p}`);
     console.error("Refusing to remove anything. This manifest is corrupt or hand-edited — fix vinaya.config.json, then re-run.");
@@ -5315,17 +5345,9 @@ async function runInitProduct(args, deps) {
     console.error("Error: this repo is not Vinaya-initialized yet. Run `vinaya init` first.");
     return 1;
   }
-  const noRemote = !repo.owner || !repo.repo;
-  if (noRemote) {
-    console.warn("Warning: no `origin` remote (or it is not a GitHub URL) — skipping label creation. " + `Re-run 'vinaya init product ${name}' after adding a GitHub remote to create it.`);
-  }
-  const ops = noRemote ? [] : buildInitProductOps(name);
-  const plan = planInstall(ops, repo.repoRoot, new Set(existing.files));
   const registryPlan = planRegistryRow(repo.repoRoot, name, productPath, specsPath);
   process.stdout.write(`vinaya init product ${name} — the full diff:
 
-`);
-  process.stdout.write(`${renderInstallDiff(plan)}
 `);
   process.stdout.write(`── Project registry ─────────────────────────────
 `);
@@ -5346,29 +5368,11 @@ async function runInitProduct(args, deps) {
     }
   }
   applyRegistryRow(repo.repoRoot, registryPlan, name, productPath, specsPath);
-  const added = await applyInstall(plan, repo.repoRoot, deps.labelGateway(repo.repoRoot));
-  const merged = {
-    version: existing.version,
-    files: [...new Set([...existing.files, ...added.files])],
-    blocks: dedupeBlocks2([...existing.blocks, ...added.blocks]),
-    labels: [...new Set([...existing.labels, ...added.labels])]
-  };
-  writeManifest(repo.repoRoot, merged);
   process.stdout.write(`
 Governed product area '${name}' scaffolded.
 `);
   return 0;
 }
-function dedupeBlocks2(bs) {
-  const seen = new Set;
-  return bs.filter((b) => {
-    const k = `${b.path}::${b.marker}`;
-    if (seen.has(k))
-      return false;
-    seen.add(k);
-    return true;
-  });
-}
 async function initCommand(args) {
   process.exit(await runInit(args, realDeps5()));
 }
@@ -6609,15 +6613,22 @@ function parseFlags(args) {
   const map = new Map;
   for (let i = 0;i < args.length; i++) {
     const a = args[i];
-    if (a.startsWith("--")) {
-      const value = args[i + 1];
-      if (value === undefined || value.startsWith("--")) {
-        map.set(a, "");
-        continue;
-      }
-      map.set(a, value);
-      i++;
+    if (a === "--")
+      break;
+    if (!a.startsWith("--"))
+      continue;
+    const eq = a.indexOf("=");
+    if (eq > 2) {
+      map.set(a.slice(0, eq), a.slice(eq + 1));
+      continue;
+    }
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+      map.set(a, "");
+      continue;
     }
+    map.set(a, value);
+    i++;
   }
   return map;
 }
@@ -6639,6 +6650,11 @@ function requireTokenField(flags2, name) {
   return v;
 }
 function readFindingsFile(path, allowedSeverities) {
+  if (path === undefined)
+    return [];
+  if (path.trim() === "") {
+    refuseCmd("`--findings-file` was given with no path.", "Pass the path to the findings file, or omit the flag entirely if there are no findings.");
+  }
   if (!path)
     return [];
   let content;
@@ -6708,9 +6724,61 @@ function fetchComments(pr) {
   const parsed = JSON.parse(out);
   return parsed.comments.map((c) => ({ body: c.body, author: c.author?.login ?? null }));
 }
+var VALUE_FLAGS = [
+  "--brief-conformance",
+  "--config-scan",
+  "--cost",
+  "--docs",
+  "--findings-file",
+  "--model",
+  "--pr",
+  "--role",
+  "--scope",
+  "--secrets",
+  "--secrets-evidence-file",
+  "--spec-conformance",
+  "--task-id",
+  "--tests",
+  "--tokens-in",
+  "--tokens-out",
+  "--verdict"
+];
+var NULLARY_FLAGS = ["--json"];
+function unknownFlags(args, known = [...VALUE_FLAGS, ...NULLARY_FLAGS]) {
+  const out = [];
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (known.includes(a) && !NULLARY_FLAGS.includes(a)) {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("--"))
+        i++;
+      continue;
+    }
+    if (a === "--")
+      break;
+    const looksLikeFlag = a.startsWith("--") || a.startsWith("-") && a.length > 1;
+    if (!looksLikeFlag)
+      continue;
+    const name = a.split("=")[0];
+    if (!known.includes(name)) {
+      out.push(name);
+      continue;
+    }
+    if (NULLARY_FLAGS.includes(name) && a.includes("="))
+      out.push(name);
+  }
+  return out;
+}
+function rejectUnknownFlags(args, known = [...VALUE_FLAGS, ...NULLARY_FLAGS]) {
+  const unknown = unknownFlags(args, known);
+  if (unknown.length === 0)
+    return;
+  refuseCmd(`unrecognised flag${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`, `\`vinaya review post\` accepts: ${[...known].sort().join(", ")}. If you meant to preview without posting, note that this command has no dry-run flag — see atta-labs/vinaya#184.`);
+}
 async function reviewPostCommand(args) {
+  rejectUnknownFlags(args);
   const json = args.includes("--json");
-  const flags2 = parseFlags(args.filter((a) => a !== "--json"));
+  const flags2 = parseFlags(args.filter((a) => !NULLARY_FLAGS.includes(a)));
   const role = flags2.get("--role");
   if (role !== "code-reviewer" && role !== "security") {
     refuseCmd(`\`--role ${role ?? "(missing)"}\` is not \`code-reviewer\` or \`security\`.`, "Pass `--role code-reviewer` or `--role security`.");
@@ -6815,6 +6883,43 @@ function execFileForRepo(cwd) {
 }
 var PRIMARY_PORT = 3008;
 var FALLBACK_PORT = 3108;
+function parsePortFlag(args) {
+  const found = [];
+  for (let k = 0;k < args.length; k++) {
+    const a = args[k];
+    if (a === "--port") {
+      const raw2 = args[k + 1];
+      if (raw2 === undefined)
+        throw new PortFlagError("`--port` requires a port number.");
+      if (raw2.startsWith("-")) {
+        throw new PortFlagError(`\`--port ${raw2}\` is not a port number — a port is a positive integer.`);
+      }
+      found.push(raw2);
+      k++;
+    } else if (a.startsWith("--port=")) {
+      found.push(a.slice("--port=".length));
+    }
+  }
+  if (found.length === 0)
+    return null;
+  if (found.length > 1 && new Set(found).size > 1) {
+    throw new PortFlagError(`\`--port\` given more than once with different values (${found.join(", ")}).`);
+  }
+  const raw = found[0];
+  if (raw === "")
+    throw new PortFlagError("`--port` requires a port number.");
+  if (!/^[0-9]+$/.test(raw))
+    throw new PortFlagError(`\`--port ${raw}\` is not a port number.`);
+  if (raw.length > 1 && raw.startsWith("0"))
+    throw new PortFlagError(`\`--port ${raw}\` has a leading zero — write the port without it.`);
+  const port = Number(raw);
+  if (port < 1 || port > 65535)
+    throw new PortFlagError(`\`--port ${raw}\` is outside the valid range 1-65535.`);
+  return port;
+}
+
+class PortFlagError extends Error {
+}
 function resolveStudioTarget(cwd, moduleUrl = import.meta.url) {
   let dir = cwd;
   for (;; ) {
@@ -6862,13 +6967,22 @@ function ensureStudioNodeModules(bundleRoot) {
     renameSync(packed, real);
   }
 }
-async function spawnStandalone(cwd, serverPath, bundleRoot) {
+async function spawnStandalone(cwd, serverPath, bundleRoot, explicitPort) {
   ensureStudioNodeModules(bundleRoot);
   const repo = await resolveRepo(() => execFileForRepo(cwd));
-  const primaryFree = await isPortFree(PRIMARY_PORT);
-  const port = primaryFree ? PRIMARY_PORT : FALLBACK_PORT;
-  if (!primaryFree) {
-    console.info(`[studio] port ${PRIMARY_PORT} is taken — falling back to ${FALLBACK_PORT}`);
+  let port;
+  if (explicitPort !== null) {
+    if (!await isPortFree(explicitPort)) {
+      console.error(`[studio] port ${explicitPort} is taken, and \`--port\` was given explicitly — refusing to bind elsewhere.`);
+      return 1;
+    }
+    port = explicitPort;
+  } else {
+    const primaryFree = await isPortFree(PRIMARY_PORT);
+    port = primaryFree ? PRIMARY_PORT : FALLBACK_PORT;
+    if (!primaryFree) {
+      console.info(`[studio] port ${PRIMARY_PORT} is taken — falling back to ${FALLBACK_PORT}`);
+    }
   }
   const env = { HOSTNAME: "127.0.0.1", ...process.env, PORT: String(port), VINAYA_REPO_ROOT: cwd };
   if (repo)
@@ -6879,13 +6993,27 @@ async function spawnStandalone(cwd, serverPath, bundleRoot) {
   });
 }
 async function runStudio(cwd, args, moduleUrl = import.meta.url) {
+  let explicitPort;
+  try {
+    explicitPort = parsePortFlag(args);
+  } catch (err) {
+    if (err instanceof PortFlagError) {
+      console.error(`[studio] ${err.message}`);
+      return 2;
+    }
+    throw err;
+  }
   const target = resolveStudioTarget(cwd, moduleUrl);
   switch (target.kind) {
     case "workspace":
+      if (explicitPort !== null) {
+        console.error(`[studio] \`--port ${explicitPort}\` cannot apply here: this is a workspace checkout, and Studio's own dev script chooses the port. Set it there, or run against a published install.`);
+        return 2;
+      }
       return spawnDev(target.webDir, args);
     case "package": {
       const bundleRoot = join20(target.packageDir, "..", "..", "..");
-      return spawnStandalone(cwd, join20(target.packageDir, "server.js"), bundleRoot);
+      return spawnStandalone(cwd, join20(target.packageDir, "server.js"), bundleRoot, explicitPort);
     }
     case "missing":
       console.error("Vinaya Studio isn't available in this install — no published @attalabs/vinaya build bundles the Studio app yet. Inside a checkout that contains Studio's source (apps/vinaya-studio/web), `vinaya studio` runs it directly.");
@@ -7000,6 +7128,10 @@ function translateHookPaths(manifest) {
     blocks: manifest.blocks.map((b) => b.path.startsWith(".git/hooks/") ? { ...b, path: `${TRACKED_HOOK_DIR}/${b.path.slice(".git/hooks/".length)}` } : b)
   };
 }
+function extractWorkflowTrigger(content) {
+  const match = content.match(/^on:\r?\n {2}([A-Za-z0-9_]+):/m);
+  return match?.[1] ?? null;
+}
 function planUpgrade(ops, repoRoot2, manifest, routing) {
   const entries = [];
   let hasChanges = routing.arm || routing.migratesManifest || routing.strips.some((s) => s.present);
@@ -7012,6 +7144,7 @@ function planUpgrade(ops, repoRoot2, manifest, routing) {
       const exists = existsSync19(abs2);
       const owned = ownedFiles.has(op.path);
       let action;
+      let triggerChange;
       if (op.path === CONFIG_PATH || op.path === DOC_OWNERS_PATH) {
         action = "keep";
       } else if (!owned) {
@@ -7019,13 +7152,22 @@ function planUpgrade(ops, repoRoot2, manifest, routing) {
       } else if (!exists) {
         action = "recreate";
         hasChanges = true;
-      } else if (readFileSync20(abs2, "utf-8") !== op.content) {
-        action = "regenerate";
-        hasChanges = true;
       } else {
-        action = "current";
+        const diskContent = readFileSync20(abs2, "utf-8");
+        if (diskContent !== op.content) {
+          action = "regenerate";
+          hasChanges = true;
+          if (op.path.startsWith(".github/workflows/")) {
+            const from = extractWorkflowTrigger(diskContent);
+            const to = extractWorkflowTrigger(op.content);
+            if (from && to && from !== to)
+              triggerChange = { from, to };
+          }
+        } else {
+          action = "current";
+        }
       }
-      entries.push({ kind: "create-file", op, action });
+      entries.push({ kind: "create-file", op, action, ...triggerChange ? { triggerChange } : {} });
     } else if (op.kind === "managed-block") {
       const abs2 = resolveManagedBlockPath(repoRoot2, op.path);
       const owned = ownedBlocks.has(blockKey(op.path, op.marker));
@@ -7090,6 +7232,12 @@ function renderUpgradeDiff(plan) {
         case "regenerate":
           lines.push(`  ~ regenerate ${e.op.path}`);
           lines.push(indent(e.op.content));
+          if (e.triggerChange) {
+            lines.push("");
+            lines.push(`  ⚠ TRIGGER CHANGE: ${e.op.path} is moving from \`${e.triggerChange.from}\` to ` + `\`${e.triggerChange.to}\`.`);
+            lines.push("     GitHub evaluates a `pull_request` trigger from the pull request branch's own copy of the " + "workflow file, but a `pull_request_target` trigger from the copy on the BASE branch — never " + "the pull request branch's. The pull request that carries this exact change matches NEITHER: " + "as `pull_request` it no longer matches (the pull request branch now declares " + "`pull_request_target`), and as `pull_request_target` the base branch still declares the old " + "trigger until this pull request merges. No workflow run fires under either event, so this " + "file's required check-run never appears for this pull request — not failing, not pending, " + "simply absent — and a ruleset or branch-protection rule that requires it will block this pull " + "request from merging through the normal flow.");
+            lines.push("     To get this pull request merged: temporarily add a ruleset bypass actor (or, under classic " + "branch protection, a temporary admin override) for the merge, then remove it once this pull " + "request is in.");
+          }
           break;
         case "recreate":
           lines.push(`  + recreate   ${e.op.path} (recorded as owned but missing on disk)`);
@@ -7269,15 +7417,15 @@ function detectPrNumber() {
     return null;
   }
 }
-var VALUE_FLAGS = ["--reason"];
+var VALUE_FLAGS2 = ["--reason"];
 var BOOLEAN_FLAGS = ["--print-only"];
 function positionalArgs(args) {
   const result = [];
   for (let i = 0;i < args.length; i++) {
     const a = args[i];
-    if (VALUE_FLAGS.some((f) => a.startsWith(`${f}=`)))
+    if (VALUE_FLAGS2.some((f) => a.startsWith(`${f}=`)))
       continue;
-    if (VALUE_FLAGS.includes(a)) {
+    if (VALUE_FLAGS2.includes(a)) {
       i += 1;
       continue;
     }
@@ -7397,7 +7545,7 @@ var COMMANDS = [
   },
   {
     name: "init product",
-    description: "Register a project in .vinaya/projects.md (and its project:<name> label) in an already-initialized repo",
+    description: "Register a project in .vinaya/projects.md in an already-initialized repo",
     flags: [
       {
         flag: "--path <path>",
@@ -7406,8 +7554,8 @@ var COMMANDS = [
     ],
     details: [
       "Writes (or appends to) `.vinaya/projects.md` — the registry Vinaya Studio's tranche board resolves a project's board link against. Idempotent: re-running with the same name updates nothing.",
-      "Also creates a `project:<name>` label (create-if-absent) — informational only, not read by any shipped check or by Studio.",
-      "A missing GitHub remote skips the label (the one forge-reaching op) but still writes the registry row, which is a pure local file write."
+      "Reaches no forge and needs no GitHub remote or credentials: the registry row is a pure local file write, and it is deliberately NOT recorded in the ownership manifest, so `eject` does not reverse adopter-declared data.",
+      "Creates no label. Project is a field, not a label: a task Issue declares its project in the body's `**Project:**` field, and a `project:*` label is ignored wherever one still exists."
     ],
     status: "shipped"
   },
@@ -7662,6 +7810,12 @@ var COMMANDS = [
   {
     name: "studio",
     description: "Launch Vinaya Studio — runs the Studio dev app when its source (apps/vinaya-studio/web) is in a checkout above the current directory; a published install launches its bundled standalone server instead",
+    flags: [
+      {
+        flag: "--port <n>",
+        description: "Bind this exact port. Without the flag the default is unchanged — 3008, falling back to 3108 when it is taken. With it there is no fallback: a taken port is refused, so you always know which server answered. Accepts `--port 3208` and `--port=3208`. Applies to a published install; in a workspace checkout Studio's own dev script owns the port and the flag is refused."
+      }
+    ],
     details: [
       "Resolution happens in this order: a workspace checkout carrying `apps/vinaya-studio/web` (Studio's source, which lives in the attalabs monorepo — not this repository) runs the dev app directly; a published install's `studio-standalone/` bundle (fetched from attalabs' release artifact at publish time, see `scripts/bundle-studio.ts`) runs that bundled server; anything else — a publish that shipped without the bundle — gets an explicit refusal and exit 1 rather than a silent no-op.",
       "Every published `@attalabs/vinaya` build ships the `studio-standalone/` bundle: `prepack` fetches attalabs’ latest CI-built standalone Studio artifact and assembles it into the tarball before publish."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attalabs/vinaya",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Vinaya — Agentic Engineering Harness. Deterministic checks every AI coding agent must satisfy before merge.",
   "type": "module",
   "license": "Apache-2.0",

package/studio-standalone/apps/vinaya-studio/web/.next/BUILD_ID

@@ -1 +1 @@
-p5sWGp4ANwORiaX4Kk6U2
+8tXGbArNoU7_MriIVYvN0