nitm-ai-dev-toolkit 5.1.1 → 5.1.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.2] - 2026-10-21
+
+### Fixed
+
+- The `using-git-worktrees` skill uses only `.worktrees/` for project-local worktrees (the non-hidden `worktrees/` alternative is removed), expands `$HOME` in the global path, and commits the `.gitignore` change on the default branch. The Factory skill states that the worktree folder is named by the job id, not the branch, and that `factory/worktree-bootstrap.md` replaces the worktree skill's setup and baseline-test steps. The Factory README notes that tools ignoring `.gitignore` should exclude `.worktrees/`.
+
 ## [5.1.1] - 2026-10-21
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.1.1",
+  "version": "5.1.2",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.agents/skills/factory/SKILL.md

@@ -294,7 +294,8 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `.worktrees/<id>/` at the root of the main checkout (the git root, inside the repo folder). Record its absolute path in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (the git root, inside the repo folder). The folder is named by the job id, never by the branch: branch `factory/<id>` must not produce `.worktrees/factory/<id>`. Record its absolute path in `worktree_path`.
+- `factory/worktree-bootstrap.md` replaces the worktree skill's project-setup and baseline-test steps. Factory does not run those.
 - Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.

package/src/monorepo/.agents/skills/using-git-worktrees/SKILL.md

@@ -37,11 +37,10 @@ Follow this priority order:
 
 ```bash
 # Check in priority order
-ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-ls -d worktrees 2>/dev/null      # Alternative
+ls -d .worktrees 2>/dev/null
 ```
 
-**If found:** Use that directory. If both exist, `.worktrees` wins.
+**If found:** Use that directory.
 
 ### 2. Check Project Configuration
 
@@ -67,21 +66,21 @@ Which would you prefer?
 
 ## Safety Verification
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For Project-Local Directories (.worktrees)
 
 **MUST verify directory is ignored before creating worktree:**
 
 ```bash
 # Check if directory is ignored (respects local, global, and system gitignore)
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+git check-ignore -q .worktrees 2>/dev/null
 ```
 
 **If NOT ignored:**
 
 Fix immediately before proceeding:
 
-1. Add appropriate line to .gitignore
-2. Commit the change
+1. Add `.worktrees/` to .gitignore
+2. Commit the change on the default branch
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
@@ -103,11 +102,11 @@ project=$(basename "$(git rev-parse --show-toplevel)")
 ```bash
 # Determine full path
 case $LOCATION in
-  .worktrees|worktrees)
+  .worktrees)
     path="$LOCATION/$BRANCH_NAME"
     ;;
   ~/.worktrees/*)
-    path="~/.worktrees/$project/$BRANCH_NAME"
+    path="$HOME/.worktrees/$project/$BRANCH_NAME"
     ;;
 esac
 
@@ -164,8 +163,6 @@ Ready to implement <feature-name>
 | Situation                  | Action                          |
 | -------------------------- | ------------------------------- |
 | `.worktrees/` exists       | Use it (verify ignored)         |
-| `worktrees/` exists        | Use it (verify ignored)         |
-| Both exist                 | Use `.worktrees/`               |
 | Neither exists             | Check project config → Ask user |
 | Directory not ignored      | Add to .gitignore + commit      |
 | Tests fail during baseline | Report failures + ask           |

package/src/monorepo/factory/README.md

@@ -99,6 +99,8 @@ Any value other than exactly `auto` is treated as `human`.
 
 By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`. Worktrees live in `.worktrees/<id>/` at the git root; the factory adds `.worktrees/` to `.gitignore` if it is missing.
 
+Tools that do not honor `.gitignore` (Jest/Vitest test discovery, ESLint, `tsc`, workspace globs) should exclude `.worktrees/`. The local merge runs tests in the main checkout while other job worktrees may still exist.
+
 ### Worktree bootstrap
 
 Before the builder starts in a new worktree, the factory runs the steps listed in `factory/worktree-bootstrap.md`: one shell command per line, in order, from the worktree root. Typical steps install dependencies or vendored packages, copy `.env` from the main checkout, and create or migrate a database for the job. The file ships with no active steps, so edit it for your project. Each step receives `FACTORY_JOB_ID`, `FACTORY_PORT_BUILDER`, `FACTORY_WORKTREE`, and `FACTORY_MAIN_CHECKOUT`.

package/src/repo/.agents/skills/factory/SKILL.md

@@ -294,7 +294,8 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `.worktrees/<id>/` at the root of the main checkout (inside the repo folder). Record its absolute path in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (inside the repo folder). The folder is named by the job id, never by the branch: branch `factory/<id>` must not produce `.worktrees/factory/<id>`. Record its absolute path in `worktree_path`.
+- `factory/worktree-bootstrap.md` replaces the worktree skill's project-setup and baseline-test steps. Factory does not run those.
 - Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.

package/src/repo/.agents/skills/using-git-worktrees/SKILL.md

@@ -37,11 +37,10 @@ Follow this priority order:
 
 ```bash
 # Check in priority order
-ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-ls -d worktrees 2>/dev/null      # Alternative
+ls -d .worktrees 2>/dev/null
 ```
 
-**If found:** Use that directory. If both exist, `.worktrees` wins.
+**If found:** Use that directory.
 
 ### 2. Check Project Configuration
 
@@ -67,21 +66,21 @@ Which would you prefer?
 
 ## Safety Verification
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For Project-Local Directories (.worktrees)
 
 **MUST verify directory is ignored before creating worktree:**
 
 ```bash
 # Check if directory is ignored (respects local, global, and system gitignore)
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+git check-ignore -q .worktrees 2>/dev/null
 ```
 
 **If NOT ignored:**
 
 Fix immediately before proceeding:
 
-1. Add appropriate line to .gitignore
-2. Commit the change
+1. Add `.worktrees/` to .gitignore
+2. Commit the change on the default branch
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
@@ -103,11 +102,11 @@ project=$(basename "$(git rev-parse --show-toplevel)")
 ```bash
 # Determine full path
 case $LOCATION in
-  .worktrees|worktrees)
+  .worktrees)
     path="$LOCATION/$BRANCH_NAME"
     ;;
   ~/.worktrees/*)
-    path="~/.worktrees/$project/$BRANCH_NAME"
+    path="$HOME/.worktrees/$project/$BRANCH_NAME"
     ;;
 esac
 
@@ -164,8 +163,6 @@ Ready to implement <feature-name>
 | Situation                  | Action                          |
 | -------------------------- | ------------------------------- |
 | `.worktrees/` exists       | Use it (verify ignored)         |
-| `worktrees/` exists        | Use it (verify ignored)         |
-| Both exist                 | Use `.worktrees/`               |
 | Neither exists             | Check project config → Ask user |
 | Directory not ignored      | Add to .gitignore + commit      |
 | Tests fail during baseline | Report failures + ask           |

package/src/repo/factory/README.md

@@ -93,6 +93,8 @@ Any value other than exactly `auto` is treated as `human`.
 
 By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`. Worktrees live in `.worktrees/<id>/` at the repo root; the factory adds `.worktrees/` to `.gitignore` if it is missing.
 
+Tools that do not honor `.gitignore` (Jest/Vitest test discovery, ESLint, `tsc`, workspace globs) should exclude `.worktrees/`. The local merge runs tests in the main checkout while other job worktrees may still exist.
+
 ### Worktree bootstrap
 
 Before the builder starts in a new worktree, the factory runs the steps listed in `factory/worktree-bootstrap.md`: one shell command per line, in order, from the worktree root. Typical steps install dependencies or vendored packages, copy `.env` from the main checkout, and create or migrate a database for the job. The file ships with no active steps, so edit it for your project. Each step receives `FACTORY_JOB_ID`, `FACTORY_PORT_BUILDER`, `FACTORY_WORKTREE`, and `FACTORY_MAIN_CHECKOUT`.