LESSONS.md

@@ -126,6 +126,14 @@ Two forks independently fixed `references/sources.md` with different approaches
 
 When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in META.md. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run.
 
+## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only
+
+`/root/ai-development/.git` has `core.bare = true` — the root directory itself has no working tree. Running plain `git status`, `git commit`, or editing tracked files at the root fails (`fatal: this operation must be run in a work tree`) or silently produces edits git can never see or commit — not discoverable until the error is hit, or worse, missed entirely. All real work — including one-line docs fixes — requires `git worktree add <path> -b <branch> origin/main` first. Fresh worktrees also don't have submodules (`tests/bats`, `docs/wiki`, etc.) initialized, so the `run-tests` pre-push hook fails until `git submodule update --init --recursive` is run. Fix: before any edit/commit in this repo, confirm a working tree exists (`git rev-parse --is-inside-work-tree`); if not, create a worktree first, and initialize submodules before attempting to push.
+
+## 2026-07-05 — Local remote-tracking refs go stale; verify against the Gitea API before asking
+
+After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch -a` still showed the remote feature branch — the local `remotes/origin/*` ref hadn't been pruned. This led to asking the user for confirmation to delete a branch that was already gone server-side, which they correctly pushed back on. Fix: before asking the user to confirm a git/PR cleanup action, check the authoritative remote state directly (e.g. `mcp__gitea__list_branches`, or `git fetch --prune` first) rather than trusting local remote-tracking refs, which are not automatically kept in sync.
+
 ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
 
 During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.

tests/run-bats.sh

@@ -7,8 +7,12 @@ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 BATS="$REPO_ROOT/tests/bats/bin/bats"
 
 if [[ ! -x "$BATS" ]]; then
-    echo "Error: bats not found at $BATS" >&2
-    echo "       Run: git submodule update --init --recursive" >&2
+    echo "bats not found at $BATS — initializing submodules..." >&2
+    git -C "$REPO_ROOT" submodule update --init --recursive
+fi
+
+if [[ ! -x "$BATS" ]]; then
+    echo "Error: bats still not found at $BATS after submodule init" >&2
     exit 1
 fi