@chronova/wiki-agent 1.5.1 → 1.6.1

package/dist/prompt.js

@@ -34,8 +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.
 
-You cannot run build tools, package managers, test runners, scripts, or any program other than git (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 (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.
 
 # 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.
@@ -69,6 +70,17 @@ Use only the tools listed above. Do not invent files, modules, APIs, business ru
 - Keep the initial documentation set focused: quickstart plus the smallest set of section pages needed to explain the repo clearly.
 - Before writing documentation, read AGENTS.md or CLAUDE.md from the repository root if either exists, and apply all conventions, code style rules, and constraints documented there.
 
+# Staging PR staleness check (update runs only)
+- Before writing any files in an update run, check whether there is already an open wiki staging pull request with newer content. If there is, abandon the update — do not call write_file or edit_file.
+- Step 1: List open PRs with branch names:
+  gh pr list --state open --json number,headRefName,title
+- Step 2: Filter for branches matching the pattern wiki/staging-<timestamp>. The timestamp is a Unix epoch in seconds (an integer, from 'date +%s' in the workflow). Extract the integer from the headRefName. Ignore the updatedAt field — use only the branch-name timestamp for comparison.
+- 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.
+- 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.
+
 # Loop prevention
 - Work in phases: discover → plan → write → verify. Do not restart discovery once you have moved to planning or writing.
 - Track what you have already inspected. If you are about to run the same command or read the same file a second time, stop — you already have that information.
@@ -107,7 +119,7 @@ Update the existing wiki documentation for this repository.
 
 Inspect .wiki/, identify recent source changes or newly relevant evidence, and refresh only the documentation pages directly affected by those changes. Use the git evidence below when available. Keep edits surgical: do not rewrite accurate sections, do not update source maps or git evidence just to refresh them, and do not make formatting-only changes. If the wiki is already current, do not edit files.
 
-Make one focused discovery pass to identify what changed, then proceed to surgical edits. Do not loop on repeated exploration steps.
+Make one focused discovery pass to identify what changed, then proceed to surgical edits. Do not loop on repeated exploration steps. Before writing any files, perform the staging PR staleness check described in the system prompt — if a newer open staging PR exists, abandon the update.
 
 Git change summary:
 ${gitSummary ?? "(not available)"}

package/dist/tools.js

@@ -439,6 +439,74 @@ export function createTools(projectRoot) {
             }
         },
     };
+    const ghTool = {
+        definition: {
+            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.).",
+                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'.",
+                        },
+                    },
+                    required: ["args"],
+                },
+            },
+        },
+        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`).
+            const BLOCKED_ACTIONS = {
+                create: true, edit: true, close: true, reopen: true, merge: true,
+                delete: true, ready: true, review: true, comment: 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,
+            };
+            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).`;
+            }
+            // 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).`;
+            }
+            // Reject shell metacharacters that could chain commands or inject
+            // flags, same guard as the git tool.
+            if (/[;&|`$()<>]/.test(argString)) {
+                return "Error: shell metacharacters are not permitted in gh arguments.";
+            }
+            try {
+                const { stdout, stderr } = await execAsync(`gh ${argString}`, {
+                    cwd: projectRoot,
+                    maxBuffer: 1024 * 1024,
+                    timeout: 30_000,
+                });
+                const result = stdout + (stderr ? `\n${stderr}` : "");
+                return truncateResult(result || "(no output)");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return truncateResult(`Error: ${message}`);
+            }
+        },
+    };
     return [
         readFileTool,
         writeFileTool,
@@ -449,6 +517,7 @@ export function createTools(projectRoot) {
         gitTool,
         astGrepTool,
         astSearchTool,
+        ghTool,
     ];
 }
 /**

package/package.json

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