@chronova/wiki-agent 1.6.5 → 1.7.0

package/dist/prompt.js

@@ -34,9 +34,9 @@ You have a FIXED, LIMITED set of tools. You CANNOT execute arbitrary commands on
 - ast_search: search code using an inline ast-grep YAML rule. More powerful than ast_grep — supports relational/inside/has constraints. Use for complex structural queries a single pattern cannot express.
 - write_file, edit_file: write or edit documentation files. These are the ONLY mutating tools and are constrained to paths under .wiki/.
 - git: run a READ-ONLY git subcommand (log, diff, show, ls-files, blame, status, remote, describe, rev-parse, shortlog, name-rev, ls-tree, cat-file, reflog). This is the ONLY way to access repository history. Mutating git operations and arbitrary shell commands are NOT available — do not attempt them and do not assume any command outside this list will work.
-- gh: run a READ-ONLY GitHub CLI (gh) subcommand in the project root. Use to inspect open pull requests, check wiki staging PR branches, and compare timestamps. Only read-only inspection subcommands are allowed (pr list, pr view, pr diff, pr checks, repo view, issue list, issue view, run list, run view, search, release list, release view, label list, workflow list, workflow view). Mutating operations (create, edit, close, merge, delete, etc.) are blocked.
+- gh: run a GitHub CLI (gh) subcommand in the project root. Read-only inspection is always allowed (pr list, pr view, pr diff, repo view, issue list, etc.). Two mutating operations are permitted ONLY on wiki staging PRs (branches matching wiki/staging-*): 'pr close' and 'pr comment'. All other mutating operations (create, merge, edit, delete, etc.) are blocked.
 
-You cannot run build tools, package managers, test runners, scripts, or any program other than git (read-only) and gh (read-only). If documentation requires information only obtainable by executing code, say so explicitly rather than attempting to run it. Ground every important claim in source files, existing docs, or git evidence you have inspected.
+You cannot run build tools, package managers, test runners, scripts, or any program other than git (read-only) and gh. If documentation requires information only obtainable by executing code, say so explicitly rather than attempting to run it. Ground every important claim in source files, existing docs, or git evidence you have inspected.
 
 # Output location
 - Write documentation under .wiki/ in the project root. Use paths such as .wiki/quickstart.md, .wiki/architecture/overview.md, .wiki/cli/usage.md.
@@ -78,8 +78,12 @@ Use only the tools listed above. Do not invent files, modules, APIs, business ru
 - Step 3: Get the repository's latest commit timestamp (also Unix seconds):
   git log -1 --format=%ct
 - Step 4: Compare the integers. If any open staging PR's branch timestamp is greater than or equal to the latest commit timestamp, that staging PR already reflects this commit (or a newer one). Abandon the update: do not write or edit any files. State that a newer staging PR already exists (include the PR number and branch name) and stop.
+- Step 5: Close stale staging PRs. For every open wiki/staging-* PR whose branch timestamp is LESS than the latest commit timestamp (i.e. it is older than the current commit), close it with a comment:
+  gh pr comment <number> --body "This branch is from an earlier staging run and is stale. Closing"
+  gh pr close <number>
+  Do this BEFORE proceeding with your own update. This keeps the PR queue clean and avoids confusing reviewers with outdated snapshots.
 - If the gh command fails (e.g. gh is not authenticated, no GitHub remote), skip this check and proceed with the update normally.
-- This check prevents duplicate staging PRs and avoids overwriting a newer pending review with older content.
+- This check prevents duplicate staging PRs, closes stale ones, and avoids overwriting a newer pending review with older content.
 
 # Loop prevention
 - Work in phases: discover → plan → write → verify. Do not restart discovery once you have moved to planning or writing.

package/dist/tools.js

@@ -444,13 +444,13 @@ export function createTools(projectRoot) {
             type: "function",
             function: {
                 name: "gh",
-                description: "Run a read-only GitHub CLI (gh) subcommand in the project root. Use to inspect open pull requests, check wiki staging PR branches, and compare timestamps. Only read-only inspection subcommands are permitted — no mutating operations (create, edit, close, merge, delete, etc.).",
+                description: "Run a GitHub CLI (gh) subcommand in the project root. Read-only inspection (pr list, pr view, pr diff, repo view, issue list, etc.) is always allowed. Two mutating operations are permitted but ONLY on wiki staging PRs (branches matching wiki/staging-*): `gh pr close <number>` and `gh pr comment <number> --body <text>`. Use to inspect open PRs, check staging branch timestamps, and close stale wiki staging PRs with a comment.",
                 parameters: {
                     type: "object",
                     properties: {
                         args: {
                             type: "string",
-                            description: "gh subcommand and arguments, without the leading 'gh'. Example: 'pr list --state open --head wiki/staging-* --json headRefName,updatedAt,number,title', 'pr view <number> --json updatedAt,headRefName,body', 'pr view <number> --json files'.",
+                            description: "gh subcommand and arguments, without the leading 'gh'. Example: 'pr list --state open --json number,headRefName,title', 'pr view <number> --json headRefName', 'pr close <number> --comment \"This branch is from an earlier staging run and is stale. Closing\"', 'pr comment <number> --body \"stale\"'.",
                         },
                     },
                     required: ["args"],
@@ -459,33 +459,57 @@ export function createTools(projectRoot) {
         },
         handler: async (args) => {
             const argString = args.args ?? "";
-            // Only read-only / inspection subcommands are permitted. The agent
-            // cannot mutate GitHub state through this tool.
             const ALLOWED_GH_SUBCOMMANDS = {
                 pr: true, issue: true, repo: true, run: true, api: true,
                 "search": true, release: true, label: true, workflow: true,
             };
-            // Mutating subcommand prefixes that must never run, even under an
-            // allowed top-level command (e.g. `gh pr create`, `gh pr merge`).
+            // Actions that are always blocked (never safe for an automated agent).
             const BLOCKED_ACTIONS = {
-                create: true, edit: true, close: true, reopen: true, merge: true,
-                delete: true, ready: true, review: true, comment: true,
+                create: true, edit: true, reopen: true, merge: true,
+                delete: true, ready: true, review: true,
                 lock: true, unlock: true, assign: true, unassign: true,
                 label: true, unlabel: true, transfer: true, archive: true,
                 unarchive: true, deploy: true, rerun: true, cancel: true,
                 publish: true, set: true, add: true, remove: true,
             };
+            // Actions allowed ONLY on wiki staging PRs (branches matching
+            // wiki/staging-*). The handler verifies the PR's headRefName before
+            // executing these.
+            const STAGING_ONLY_ACTIONS = {
+                close: true, comment: true,
+            };
             const tokens = argString.trim().split(/\s+/);
             const subcommand = tokens[0] ?? "";
             if (!ALLOWED_GH_SUBCOMMANDS[subcommand]) {
-                return `Error: gh subcommand '${subcommand}' is not permitted. Only read-only inspection subcommands are allowed (pr, issue, repo, run, api, search, release, label, workflow).`;
+                return `Error: gh subcommand '${subcommand}' is not permitted. Only inspection subcommands and pr close/comment on wiki staging PRs are allowed (pr, issue, repo, run, api, search, release, label, workflow).`;
             }
-            // For `gh pr` and similar, check the action token (second token)
-            // against the blocklist. `gh pr list`, `gh pr view`, `gh pr diff`,
-            // `gh pr checks` are read-only and allowed.
             const action = tokens[1] ?? "";
             if (BLOCKED_ACTIONS[action]) {
-                return `Error: gh ${subcommand} ${action} is a mutating operation. Only read-only inspection is allowed (list, view, diff, checks, status).`;
+                return `Error: gh ${subcommand} ${action} is a blocked operation.`;
+            }
+            // For close/comment on PRs, verify the target is a wiki staging PR.
+            // The PR number is the third token: 'gh pr close <number>' or
+            // 'gh pr comment <number> --body ...'.
+            if (STAGING_ONLY_ACTIONS[action] && subcommand === "pr") {
+                const prNumber = tokens[2] ?? "";
+                if (!/^\d+$/.test(prNumber)) {
+                    return `Error: a valid PR number is required for gh pr ${action}.`;
+                }
+                // Fetch the PR's headRefName to verify it's a wiki staging branch.
+                try {
+                    const { stdout } = await execAsync(`gh pr view ${prNumber} --json headRefName`, { cwd: projectRoot, maxBuffer: 1024 * 1024, timeout: 30_000 });
+                    const parsed = JSON.parse(stdout);
+                    if (!parsed.headRefName?.startsWith("wiki/staging-")) {
+                        return `Error: gh pr ${action} is only permitted on wiki staging PRs (branches matching wiki/staging-*). PR #${prNumber} has headRefName '${parsed.headRefName ?? "unknown"}'.`;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return `Error: could not verify PR #${prNumber} is a wiki staging PR: ${message}`;
+                }
+            }
+            else if (STAGING_ONLY_ACTIONS[action]) {
+                return `Error: gh ${subcommand} ${action} is not supported. Only gh pr ${action} is permitted, and only on wiki staging PRs.`;
             }
             // Reject shell metacharacters that could chain commands or inject
             // flags, same guard as the git tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronova/wiki-agent",
-  "version": "1.6.5",
+  "version": "1.7.0",
   "description": "Standalone Ollama-only documentation agent",
   "type": "module",
   "bin": {