merge: bring the v2.8.0 stable line into preview

preview stalled at 2026-07-28 while v2.7.43 and v2.8.0 both shipped from
main, so the npm preview dist-tag (2.7.43-preview.20260728) sat below
latest (2.8.0). Resolve to main's tree exactly: the two conflicting paths
(package.json version, tests/repo-hygiene.test.ts) already carry the
landed form on main.

Author: lidge-jun

.github/AGENTS.md

@@ -0,0 +1,26 @@
+# GitHub automation instructions
+
+This file applies to `.github/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Security boundary
+
+Every workflow, ownership, branch-enforcement, release, or repository-automation
+change requires explicit security review under `MAINTAINERS.md`.
+
+## Workflow rules
+
+- Grant the minimum required `permissions`.
+- Pin third-party actions to immutable full commit SHAs.
+- Preserve the human-readable version comment beside each pinned action.
+- Do not run untrusted pull-request code with secrets or write permissions.
+- Treat `pull_request_target`, workflow dispatch, reusable workflows, artifacts, caches, and generated command input as trust boundaries.
+- Do not broaden triggers, write permissions, token exposure, release eligibility, or publish capability without an explicit task requirement.
+- Preserve cross-platform coverage where the workflow currently promises Linux, macOS, and Windows behavior.
+- Keep branch-enforcement text synchronized with `AGENTS.md`, `MAINTAINERS.md`, and the public contributing guide.
+
+## Validation
+
+- Inspect the complete workflow diff, including event triggers, permissions, conditions, interpolation, and shell behavior.
+- Run the local commands represented by changed workflow steps where possible.
+- Run `bun run prepush` for CI, release, dependency, packaging, or cross-platform workflow changes.
+- Do not claim the workflow itself passed until GitHub Actions reports success for the exact commit.

.github/CODEOWNERS

@@ -14,5 +14,7 @@
 /src/server/management-api.ts @lidge-jun @Ingwannu
 
 # Governance and security policy
+/AGENTS.md @lidge-jun @Ingwannu
+**/AGENTS.md @lidge-jun @Ingwannu
 /MAINTAINERS.md @lidge-jun @Ingwannu
 /SECURITY.md @lidge-jun @Ingwannu

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Report a security vulnerability (private)
+    url: https://github.com/lidge-jun/opencodex/security/advisories/new
+    about: Report undisclosed vulnerabilities privately to the maintainers. Do not open a public issue.
   - name: Security policy
     url: https://github.com/lidge-jun/opencodex/blob/main/SECURITY.md
     about: Read the supported-version and reporting guidance before sharing security-sensitive details.

.github/scripts/enforce-pr-target.test.cjs

@@ -0,0 +1,86 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+
+describe("enforce-pr-target workflow", () => {
+  const workflowPath = path.join(__dirname, "../workflows/enforce-pr-target.yml");
+  const workflow = fs.readFileSync(workflowPath, "utf8");
+
+  it("uses pull_request_target without checking out PR head code", () => {
+    assert.match(workflow, /pull_request_target:/);
+    assert.doesNotMatch(
+      workflow,
+      /ref:\s*\$\{\{\s*github\.event\.pull_request\.head/,
+      "enforcer must not check out untrusted PR head code",
+    );
+  });
+
+  it("grants contents:write so draft GraphQL mutations work with GITHUB_TOKEN", () => {
+    // convertPullRequestToDraft / markPullRequestReadyForReview fail with
+    // "Resource not accessible by integration" when contents stays unset/read
+    // (seen on #626). Assert the real permissions block, not comment text
+    // that also mentions these scopes.
+    const permissionsBlock = workflow.match(/^permissions:\n((?:[ \t]+.+\n)+)/m);
+    assert.ok(permissionsBlock, "workflow must declare a top-level permissions block");
+    const lines = permissionsBlock[1]
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .sort();
+    assert.deepEqual(lines, ["contents: write", "pull-requests: write"]);
+  });
+
+  it("fails the required check on a wrong base even if draft conversion fails", () => {
+    assert.match(workflow, /core\.setFailed\(/);
+    assert.match(workflow, /draftConversionFailed/);
+    assert.match(workflow, /Could not convert pull request to draft/);
+  });
+
+  it("soft-fails ready-for-review restoration the same way", () => {
+    assert.match(workflow, /readyConversionFailed/);
+    assert.match(workflow, /Could not mark pull request ready for review/);
+  });
+
+  it("listens for synchronize so rebase can clear ancestry failures", () => {
+    assert.match(workflow, /synchronize/);
+  });
+
+  it("checks out trusted default-branch scripts only (never PR head)", () => {
+    assert.match(workflow, /actions\/checkout@[0-9a-f]{40}/);
+    assert.match(workflow, /ref:\s*\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/);
+    assert.match(workflow, /sparse-checkout:\s*\.github\/scripts/);
+    assert.match(workflow, /persist-credentials:\s*false/);
+    assert.doesNotMatch(workflow, /ref:\s*\$\{\{\s*github\.event\.pull_request\.head/);
+  });
+
+  it("loads pr-quality via require from the checked-out scripts", () => {
+    assert.match(workflow, /pr-quality\.cjs/);
+    assert.match(workflow, /collectPrQualityFailures/);
+  });
+
+  it("checks stacked bases via open PR heads before wrong_base enforcement", () => {
+    assert.match(workflow, /stackedBase/);
+    assert.match(workflow, /github\.rest\.pulls\.list/);
+    assert.match(workflow, /treating as stacked/);
+    const qualityCall = workflow.match(
+      /collectPrQualityFailures\(\{([\s\S]*?)\}\);/,
+    );
+    assert.ok(qualityCall, "must call collectPrQualityFailures");
+    assert.match(qualityCall[1], /stackedBase/);
+  });
+
+  it("strips stale WRONG BRANCH prefix on failure when base is corrected", () => {
+    const failureBlock = workflow.match(
+      /if \(failures\.length > 0\) \{([\s\S]*?)core\.setFailed\(/,
+    );
+    assert.ok(failureBlock, "workflow must have a failure path");
+    const failurePath = failureBlock[1];
+    assert.match(failurePath, /shouldStripTitlePrefix/);
+    assert.match(failurePath, /!hasWrongBase/);
+    assert.match(failurePath, /titlePrefixedByBot = false/);
+    assert.match(failurePath, /pr\.title\.slice\(TITLE_PREFIX\.length\)/);
+  });
+});

.github/scripts/issue-quality.cjs

@@ -25,19 +25,29 @@ function unwrapSingleEnclosingFence(text) {
   return match[2];
 }
 
-function isPlaceholderOnlyValue(raw) {
-  if (typeof raw !== "string") return false;
+/**
+ * Shared strip/trim/unwrap used by placeholder and unusable-stand-in matchers.
+ * Returns null when the value is absent after normalisation.
+ */
+function normalizeRawSectionValue(raw) {
+  if (typeof raw !== "string") return null;
   let value = raw.replace(/<!--[\s\S]*?-->/g, "").trim();
-  if (!value) return false;
+  if (!value) return null;
 
-  // A lone fenced block whose entire body is a placeholder is still placeholder
-  // text (e.g. ```text\nN/A\n```), not a real example.
+  // A lone fenced block whose entire body is a stand-in is still a stand-in
+  // (e.g. ```text\nN/A\n```), not a real example.
   const unwrapped = unwrapSingleEnclosingFence(value);
   if (unwrapped !== null) {
     value = unwrapped.trim();
-    if (!value) return false;
+    if (!value) return null;
   }
 
+  return value;
+}
+
+function isPlaceholderOnlyValue(raw) {
+  const value = normalizeRawSectionValue(raw);
+  if (value === null) return false;
   return PLACEHOLDER_ONLY_RE.test(value);
 }
 
@@ -374,7 +384,10 @@ function detectIssueKind(issue) {
 // ---------------------------------------------------------------------------
 
 function isEmpty(text) {
-  return clean(text).length === 0;
+  const c = clean(text);
+  if (c.length === 0) return true;
+  // Stand-ins like "...", "…", "---" are not actionable report content.
+  return /^[\p{P}\p{S}\s]+$/u.test(c);
 }
 
 function allSameCanonical(sections) {
@@ -395,6 +408,20 @@ function isPlaceholder(text) {
   return isPlaceholderOnlyValue(text);
 }
 
+/**
+ * True when Version is an "I don't know" stand-in rather than an install id.
+ * Kept separate from PLACEHOLDER_ONLY_RE so legacy N/A / No response soft-pass
+ * behaviour is unchanged.
+ */
+const UNUSABLE_VERSION_RE =
+  /^[\s_*~`]*(?:unknown|unkown|uknown|don'?t\s+know|do\s+not\s+know|idk|dunno|not\s+sure|unsure|\?+|모름|잘\s*모름|모르겠(?:습니다|음)?|不明|わからない|分からない|不知道|不清楚|keine\s+ahnung|wei[sß]{1,2}\s+nicht)[\s_*~`]*[.!?]*$/i;
+
+function isUnusableVersion(raw) {
+  const value = normalizeRawSectionValue(raw);
+  if (value === null) return false;
+  return UNUSABLE_VERSION_RE.test(value);
+}
+
 const CJK_RE =
   /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
 
@@ -430,6 +457,16 @@ function isTooTerseFeatureSection(text) {
   return true;
 }
 
+/**
+ * Bug Reproduction needs steps or concrete signals. A title-like phrase with
+ * no commands, paths, digits, or product keywords is not actionable.
+ */
+function isTooTerseBugReproduction(text) {
+  if (isEmpty(text) || isPlaceholder(text)) return false;
+  if (hasConcreteDetail(text)) return false;
+  return countWords(text) < 12;
+}
+
 /**
  * Check if raw section text is a placeholder-only variant without relying on
  * clean() first. Used to distinguish intentionally blank optional fields
@@ -625,6 +662,8 @@ function validateIssue(issue) {
     const repro = extractSection(body, "Reproduction");
     const version = extractSection(body, "Version");
     const os = extractSection(body, "Operating system") ?? extractSection(body, "OS");
+    // New Bug report template always includes Client or integration.
+    const isNewBugForm = extractSection(body, "Client or integration") !== null;
 
     if (isEmpty(summary) && isEmpty(repro)) {
       // Soft-pass substantial non-English / freeform structured reports once
@@ -642,16 +681,65 @@ function validateIssue(issue) {
         reasons.push("Both Summary and Reproduction are empty.");
         guidance.push("Describe what happened and how to reproduce it.");
       }
+    } else {
+      // Each mapped field is required on its own — a filled Summary with an
+      // empty / ellipsis Reproduction (e.g. #598) must not pass.
+      if (isEmpty(summary)) {
+        reasons.push("Summary is empty.");
+        guidance.push("Describe what happened (the symptom or error).");
+      }
+      if (isEmpty(repro)) {
+        reasons.push("Reproduction is empty.");
+        guidance.push("List the exact steps to reproduce the problem.");
+      } else if (!softPass && isTooTerseBugReproduction(repro)) {
+        reasons.push("Reproduction is too vague to act on.");
+        guidance.push("List exact steps, commands, and the observed failure — not only a short phrase.");
+      }
     }
 
-    // Required environment fields removed after submission.
-    // Only fire when the headings exist in the body (new form). Legacy bug
-    // reports never had Version or OS fields, so null means absent, not removed.
-    // Skip when the raw value is a "No response" placeholder -- the old form had
-    // both fields as optional, so legacy issues legitimately contain those headings
-    // with the GitHub placeholder. Only close when the field was actively cleared.
-    if (!softPass && version !== null && os !== null && isEmpty(version) && isEmpty(os) &&
-        !isRawPlaceholder(version) && !isRawPlaceholder(os)) {
+    // Version "Unknown" / "모름" / "idk" is never actionable, on any form.
+    if (!softPass && version !== null && isUnusableVersion(version)) {
+      reasons.push("Version is missing or unknown.");
+      guidance.push("Report the installed `@bitkyc08/opencodex` version (for example `2.7.42`) or a commit SHA from `ocx --version`.");
+    } else if (
+      !softPass &&
+      isNewBugForm &&
+      (version === null || isEmpty(version) || isRawPlaceholder(version))
+    ) {
+      // New form requires Version (including when the heading was removed).
+      // Legacy N/A / No response soft-pass stays only for bodies without
+      // Client or integration.
+      reasons.push("Version is missing.");
+      guidance.push("Add your OpenCodex version so we can reproduce the environment.");
+    }
+
+    if (!softPass && isNewBugForm && os !== null && isUnusableVersion(os)) {
+      reasons.push("Operating system is missing or unknown.");
+      guidance.push("Add your OS name and version (for example Windows 11 24H2).");
+    } else if (
+      !softPass &&
+      isNewBugForm &&
+      (os === null || isEmpty(os) || isRawPlaceholder(os))
+    ) {
+      reasons.push("Operating system is missing.");
+      guidance.push("Add your OS name and version (for example Windows 11 24H2).");
+    }
+
+    // Required environment fields removed after submission on bodies that are
+    // not the new form (no Client or integration). Legacy reports never had
+    // Version or OS fields, so null means absent, not removed. Skip when the
+    // raw value is a "No response" placeholder — the old form had both fields
+    // as optional. Only close when the field was actively cleared.
+    if (
+      !softPass &&
+      !isNewBugForm &&
+      version !== null &&
+      os !== null &&
+      isEmpty(version) &&
+      isEmpty(os) &&
+      !isRawPlaceholder(version) &&
+      !isRawPlaceholder(os)
+    ) {
       reasons.push("Version and Operating system are both missing.");
       guidance.push("Add your OpenCodex version and OS so we can reproduce the environment.");
     }
@@ -859,6 +947,7 @@ module.exports = {
   isPlaceholderOnlyValue,
   isPlaceholder,
   isRawPlaceholder,
+  isUnusableVersion,
   countWords,
   hasConcreteDetail,
   labelForKind,