@link-assistant/hive-mind 1.26.4 → 1.28.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @link-assistant/hive-mind
 
+## 1.28.0
+
+### Minor Changes
+
+- docs: expand best practices with CI/CD guide, universal prompts, and architecture improvement (Issue #1403)
+
+  Splits the existing `docs/BEST-PRACTICES.md` into two focused documents:
+  - **`docs/CI-CD-BEST-PRACTICES.md`** (renamed from the original) — Updated and expanded CI/CD guide covering all key points from existing workflow templates, including: running checks only on relevant file changes, fast-fail job ordering, fresh merge simulation, concurrency control, changeset exemptions for docs-only PRs, secrets detection, documentation validation, and OIDC trusted publishing.
+  - **`docs/BEST-PRACTICES.md`** (new general guide) — Universal best practices for AI-driven development including: deep analysis bug/feature prompts, universal validation prompt, plan mode prompt, issue writing guidelines with acceptance criteria patterns, an architecture improvement prompt linking to the Code Architecture Principles repository, CI/CD summary with link to the CI/CD guide, and subagent coordination patterns.
+
+  Also updates `README.md` to link to both new documents in the Best Practices section.
+
+  feat: enable --auto-restart-until-mergeable by default (Issue #1360)
+
+  The `--auto-restart-until-mergeable` feature has become stable enough to be enabled by default. Previously, users had to explicitly pass this flag to enable automatic restart until the PR becomes mergeable.
+
+  Now the feature is enabled by default, meaning the solver will automatically restart on new comments from non-bot users, CI failures, merge conflicts, or other issues — without requiring any extra flags. Users who want to disable this behavior can pass `--no-auto-restart-until-mergeable`.
+
+  fix: filter GitHub Pages deployment workflows from PR CI check (Issue #1399)
+
+  `getActiveRepoWorkflows()` included the `pages-build-deployment` workflow (path: `dynamic/pages/pages-build-deployment`) as if it were a PR CI workflow. This workflow is auto-created by GitHub for GitHub Pages and only runs on the default branch after merge — it never creates check-runs on PR branches. As a result, `--auto-restart-until-mergeable` got stuck in an infinite loop waiting for CI checks that would never appear.
+
+  The fix filters out workflows with the `dynamic/pages/` prefix from `getActiveRepoWorkflows()`. These are GitHub Pages internal workflows, not user-defined CI pipelines.
+
+  Affected scenario: repositories with GitHub Pages enabled but no `.github/workflows/` files (e.g., `konard/links-visuals`).
+
+  fix: resolve Prettier formatting issue in README.md (Issue #1401)
+
+  The CI/CD `lint` job was failing on the `main` branch because README.md had Prettier formatting violations after commit `da376061` ("Clarify Time Freedom and Any Device Programming features"). That commit added longer text to two table cells, which made the table column widths inconsistent with Prettier's expected format.
+
+  The fix runs `prettier --write` on README.md to re-align the table column widths, bringing the file back into conformance with the `format:check` CI step.
+
+## 1.27.0
+
+### Minor Changes
+
+- f6e909e: feat: make --gitkeep-file enabled by default for all --tools (Issue #1385)
+
+  Previously, `--claude-file` was the default for `--tool claude`, while `--gitkeep-file` was the default for other tools. Now `--gitkeep-file` is the universal default for all `--tool` values, including `--tool claude`.
+
+  As explained in the referenced video, CLAUDE.md and AGENT.md files generally do not help AI tools and should be avoided. Users who need CLAUDE.md-based task passing can still explicitly opt in with `--claude-file`.
+
 ## 1.26.4
 
 ### Patch Changes

package/README.md

@@ -21,18 +21,18 @@ Inspired by [konard/problem-solving](https://github.com/konard/problem-solving)
 
 Hive Mind is a **generalist AI** (mini-AGI) capable of working on a wide range of tasks - not just programming. Almost anything that can be done with files in a repository can be automated.
 
-| Feature                      | What It Means For You                                                                              |
-| ---------------------------- | -------------------------------------------------------------------------------------------------- |
-| **No Babysitting**           | Full autonomous mode with sudo access. AI has creative freedom like a real programmer.             |
-| **Cloud Isolation**          | Runs on dedicated VMs or Docker. Easy to restore if broken.                                        |
-| **Full Internet + Sudo**     | AI can install packages, fetch docs, and configure the system as needed.                           |
-| **Pre-installed Toolchain**  | 25GB+ ready: 10 language runtimes, 2 theorem provers, build tools. Can install more.               |
-| **Token Efficiency**         | Routine tasks automated in code, so AI tokens focus on creative problem-solving.                   |
-| **Time Freedom**             | What takes humans 2-8 hours, AI completes in 10-25 minutes. "The code is written while you sleep." |
-| **Scale with Orchestration** | Parallel workers feel like a team of developers, all for ~$200/month.                              |
-| **Human Control**            | AI creates draft PRs - you decide what merges. Quality gates where they matter.                    |
-| **Any Device Programming**   | Manage AI from any device with `/solve` and `/hive`. No PC, IDE, or laptop required.               |
-| **100% Open Source**         | Unlicense (public domain). Full transparency, no vendor lock-in.                                   |
+| Feature                      | What It Means For You                                                                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **No Babysitting**           | Full autonomous mode with sudo access. AI has creative freedom like a real programmer.                                                                                     |
+| **Cloud Isolation**          | Runs on dedicated VMs or Docker. Easy to restore if broken.                                                                                                                |
+| **Full Internet + Sudo**     | AI can install packages, fetch docs, and configure the system as needed.                                                                                                   |
+| **Pre-installed Toolchain**  | 25GB+ ready: 10 language runtimes, 2 theorem provers, build tools. Can install more.                                                                                       |
+| **Token Efficiency**         | Routine tasks automated in code, so AI tokens focus on creative problem-solving.                                                                                           |
+| **Time Freedom**             | What takes humans 2-8 hours, AI completes each working session in 10-25 minutes. Mass execution of tasks in repository is possible. "The code is written while you sleep." |
+| **Scale with Orchestration** | Parallel workers feel like a team of developers, all for ~$200/month.                                                                                                      |
+| **Human Control**            | AI creates draft PRs - you decide what merges. Quality gates where they matter.                                                                                            |
+| **Any Device Programming**   | Manage AI from any device with `/solve` and `/hive` via Telegram bot. No PC, IDE, or laptop required.                                                                      |
+| **100% Open Source**         | Unlicense (public domain). Full transparency, no vendor lock-in.                                                                                                           |
 
 > _"Compared to Codex for $200, this solution is fire."_ - User feedback
 
@@ -404,9 +404,9 @@ The Hive Mind includes a Telegram bot interface (SwarmMindBot) for remote comman
 
 ### 🚀 Test Drive
 
-Want to see the Hive Mind in action? Join our Telegram channel where you can execute the Hive Mind on your own issues and watch AI solve them:
+Want to see the Hive Mind in action? Request a free demo or get faster support by messaging the developer directly on Telegram:
 
-**[Join https://t.me/hive_mind_pull_requests](https://t.me/hive_mind_pull_requests)**
+**[Message @drakonard on Telegram](https://t.me/drakonard)**
 
 ### Setup
 
@@ -839,6 +839,30 @@ screen -wipe
 screen -ls
 ```
 
+### Top with full arguments of each command
+
+```bash
+top -c
+```
+
+### See the full tree of processes
+
+```bash
+ps -eo pid,ppid,user,args --forest
+```
+
+or
+
+```bash
+ps axjf
+```
+
+### Kill all commands spawned by specific task
+
+```bash
+pkill -f gh-issue-solver-1773073065743
+```
+
 That can be done, but not recommended as reboot have better effect.
 
 ## 📄 License
@@ -847,7 +871,10 @@ Unlicense License - see [LICENSE](./LICENSE)
 
 ## 🏆 Best Practices
 
-Hive Mind works even better when repositories have strong CI/CD pipelines. See [BEST-PRACTICES.md](./docs/BEST-PRACTICES.md) for recommended configurations that maximize AI solver quality.
+Hive Mind works even better when repositories have strong CI/CD pipelines and clear issue requirements. See:
+
+- [BEST-PRACTICES.md](./docs/BEST-PRACTICES.md) — Universal prompts, issue writing guidelines, architecture improvement, and subagent patterns
+- [CI-CD-BEST-PRACTICES.md](./docs/CI-CD-BEST-PRACTICES.md) — CI/CD pipeline setup, recommended templates, and enforcement strategies
 
 Key benefits of proper CI/CD:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.26.4",
+  "version": "1.28.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/github-merge.lib.mjs

@@ -1403,20 +1403,31 @@ export async function getWorkflowRunsForSha(owner, repo, sha, verbose = false) {
  * When a repo has NO workflows, no_checks means no CI configured.
  * When a repo HAS workflows, no_checks means CI checks haven't started yet (race condition).
  *
+ * Issue #1399: GitHub Pages deployment workflows (path: "dynamic/pages/...") are excluded
+ * because they only run on the default branch after merge, never on PR branches. Counting
+ * them as "CI workflows" causes an infinite loop waiting for check-runs that never appear.
+ *
  * @param {string} owner - Repository owner
  * @param {string} repo - Repository name
  * @param {boolean} verbose - Whether to log verbose output
- * @returns {Promise<{count: number, hasWorkflows: boolean, workflows: Array<{id: number, name: string, state: string}>}>}
+ * @returns {Promise<{count: number, hasWorkflows: boolean, workflows: Array<{id: number, name: string, state: string, path: string}>}>}
  */
 export async function getActiveRepoWorkflows(owner, repo, verbose = false) {
   try {
-    const { stdout } = await exec(`gh api "repos/${owner}/${repo}/actions/workflows" --jq '[.workflows[] | select(.state == "active")] | map({id: .id, name: .name, state: .state})'`);
-    const workflows = JSON.parse(stdout.trim() || '[]');
+    const { stdout } = await exec(`gh api "repos/${owner}/${repo}/actions/workflows" --jq '[.workflows[] | select(.state == "active")] | map({id: .id, name: .name, state: .state, path: .path})'`);
+    const allWorkflows = JSON.parse(stdout.trim() || '[]');
+
+    // Issue #1399: Filter out GitHub Pages deployment workflows.
+    // These have path "dynamic/pages/pages-build-deployment" and only run on the
+    // default branch after merge — they never produce check-runs on PR branches.
+    // Including them causes an infinite loop when waiting for PR CI checks.
+    const workflows = allWorkflows.filter(wf => !wf.path.startsWith('dynamic/pages/'));
 
     if (verbose) {
-      console.log(`[VERBOSE] /merge: Found ${workflows.length} active workflows in ${owner}/${repo}`);
-      for (const wf of workflows) {
-        console.log(`[VERBOSE] /merge:   - ${wf.name} (${wf.id}): ${wf.state}`);
+      console.log(`[VERBOSE] /merge: Found ${allWorkflows.length} active workflows in ${owner}/${repo} (${workflows.length} PR-relevant after filtering out GitHub Pages deployment workflows)`);
+      for (const wf of allWorkflows) {
+        const filtered = wf.path.startsWith('dynamic/pages/');
+        console.log(`[VERBOSE] /merge:   - ${wf.name} (${wf.id}): ${wf.state}, path=${wf.path}${filtered ? ' [excluded: GitHub Pages deployment]' : ''}`);
       }
     }
 

package/src/solve.auto-pr.lib.mjs

@@ -70,8 +70,8 @@ export async function handleAutoPrCreation({ argv, tempDir, branchName, issueNum
         }
       }
     } else {
-      // .gitkeep mode (via explicit --gitkeep-file or auto-gitkeep-file fallback)
-      const modeDesc = argv.gitkeepFile === true ? '.gitkeep (explicit --gitkeep-file)' : '.gitkeep (CLAUDE.md is ignored)';
+      // .gitkeep mode (default for all tools, or auto-gitkeep-file fallback)
+      const modeDesc = argv.claudeFile === false ? '.gitkeep (default)' : '.gitkeep (CLAUDE.md is ignored)';
       await log(formatAligned('📝', 'Creating:', modeDesc));
 
       filePath = path.join(tempDir, '.gitkeep');
@@ -133,7 +133,7 @@ Proceed.
       }
     } else {
       // .gitkeep: Use minimal metadata format (explicit --gitkeep-file or auto-gitkeep-file fallback)
-      const creationReason = argv.gitkeepFile === true ? '# This file was created with --gitkeep-file flag' : '# This file was created because CLAUDE.md is in .gitignore (--auto-gitkeep-file=true)';
+      const creationReason = argv.claudeFile === false ? '# This file was created with --gitkeep-file (default)' : '# This file was created because CLAUDE.md is in .gitignore (--auto-gitkeep-file=true)';
       const gitkeepContent = `# Auto-generated file for PR creation
 # Issue: ${issueUrl}
 # Branch: ${branchName}
@@ -297,8 +297,8 @@ ${creationReason}
     }
 
     await log(formatAligned('📝', 'Creating commit:', `With ${commitFileName} file`));
-    // Commit message distinguishes between explicit --gitkeep-file and auto-gitkeep-file fallback
-    const fileDesc = commitFileName === 'CLAUDE.md' ? 'CLAUDE.md with task information for AI processing' : `.gitkeep for PR creation (${argv.gitkeepFile === true ? 'created with --gitkeep-file flag' : 'CLAUDE.md is in .gitignore'})`;
+    // Commit message distinguishes between CLAUDE.md and .gitkeep modes
+    const fileDesc = commitFileName === 'CLAUDE.md' ? 'CLAUDE.md with task information for AI processing' : `.gitkeep for PR creation (${argv.claudeFile === false ? 'default mode' : 'CLAUDE.md is in .gitignore'})`;
     const commitMessage = `Initial commit with task details\n\nAdding ${fileDesc}.\nThis file will be removed when the task is complete.\n\nIssue: ${issueUrl}`;
 
     // Use explicit cwd option for better reliability

package/src/solve.config.lib.mjs

@@ -101,13 +101,13 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'claude-file': {
     type: 'boolean',
-    description: 'Create CLAUDE.md file for task details (default for --tool claude, mutually exclusive with --gitkeep-file)',
-    default: true,
+    description: 'Create CLAUDE.md file for task details (mutually exclusive with --gitkeep-file)',
+    default: false,
   },
   'gitkeep-file': {
     type: 'boolean',
-    description: 'Create .gitkeep file instead of CLAUDE.md (default for --tool agent/opencode/codex, mutually exclusive with --claude-file)',
-    default: false,
+    description: 'Create .gitkeep file instead of CLAUDE.md (default for all --tool values, mutually exclusive with --claude-file)',
+    default: true,
   },
   'auto-gitkeep-file': {
     type: 'boolean',
@@ -179,7 +179,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   'auto-restart-until-mergeable': {
     type: 'boolean',
     description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
-    default: false,
+    default: true,
   },
   'auto-restart-on-non-updated-pull-request-description': {
     type: 'boolean',
@@ -541,20 +541,6 @@ export const parseArguments = async (yargs, hideBin) => {
     argv.model = 'minimax-m2.5-free';
   }
 
-  // Tool-specific defaults for --claude-file and --gitkeep-file
-  // For non-Claude tools, use .gitkeep by default to avoid polluting CLAUDE.md
-  // (CLAUDE.md has special meaning for Claude Code as a project-level instruction file)
-  // See: https://github.com/link-assistant/hive-mind/issues/1158
-  const claudeFileExplicitlyProvided = rawArgs.includes('--claude-file') || rawArgs.includes('--no-claude-file');
-  const gitkeepFileExplicitlyProvided = rawArgs.includes('--gitkeep-file') || rawArgs.includes('--no-gitkeep-file');
-
-  if (argv.tool !== 'claude' && !claudeFileExplicitlyProvided && !gitkeepFileExplicitlyProvided) {
-    // User did not explicitly provide either option, so use the correct defaults for non-Claude tools
-    // Non-Claude tools (agent, opencode, codex) should use .gitkeep by default
-    argv.claudeFile = false;
-    argv.gitkeepFile = true;
-  }
-
   // Validate mutual exclusivity of --claude-file and --gitkeep-file
   // Check if both are explicitly enabled (user passed both --claude-file and --gitkeep-file)
   if (argv.claudeFile && argv.gitkeepFile) {
@@ -588,7 +574,7 @@ export const parseArguments = async (yargs, hideBin) => {
     argv.claudeFile = false;
   }
 
-  // If user explicitly set --no-gitkeep-file, enable claude-file (this is the default anyway)
+  // If user explicitly set --no-gitkeep-file, enable claude-file
   if (noGitkeepFile && !argv.claudeFile) {
     argv.claudeFile = true;
     argv.gitkeepFile = false;