@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/git-worktree/test/stale-lock-sweep.test.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# 2026-07-01 reproducer: worktree-manager.sh must self-heal a stale git lock
+# file left when a git process is killed mid-write (the 2026-07-01 seccomp
+# outage class — a residual .git/config.lock wedges every later `git config`
+# write with EEXIST forever). Age-guarded sweep: aged config locks removed,
+# fresh and future-dated locks preserved; index/HEAD locks out of scope.
+#
+# Plan: knowledge-base/project/plans/archive/20261013-041741-2026-07-01-fix-stale-git-lock-sweep-worktree-plan.md
+#
+# Run via:  bash plugins/soleur/skills/git-worktree/test/stale-lock-sweep.test.sh
+
+set -uo pipefail
+
+# Git-location tripwire (#7833). These suites drive worktree-manager.sh, which runs
+# `git worktree remove`, `git branch -D` and `git reset --hard` -- the highest-damage git writes
+# in the corpus. An inherited GIT_DIR aims all of them at the developer's real repository, so
+# this file aborts rather than proceeding. Inline rather than sourcing test-helpers.sh, which
+# would also import an assertion framework these suites do not use.
+for _v in GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_OBJECT_DIRECTORY \
+          GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_NAMESPACE GIT_TEMPLATE_DIR GIT_EXEC_PATH; do
+  if [[ -n "${!_v:-}" && "${SOLEUR_GIT_TRIPWIRE_ALLOW:-0}" != "1" ]]; then
+    printf 'FATAL: %s started with an inherited git-location environment (%s=%s).\n' \
+      "${BASH_SOURCE[0]}" "$_v" "${!_v}" >&2
+    printf 'Fix the ENTRY POINT: unset %s && <runner>\n' "$_v" >&2
+    exit 97
+  fi
+done
+unset _v
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../.." && pwd)"
+WM="$REPO_ROOT/plugins/soleur/skills/git-worktree/scripts/worktree-manager.sh"
+
+PASS=0; FAIL=0
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+pass() { echo "  pass: $1"; PASS=$((PASS+1)); }
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+# GNU coreutils preflight — the sweep + this test use GNU `stat -c%Y` and
+# `touch -d '<rel>'` (Linux/CI ubuntu target). Skip cleanly on a non-GNU host
+# (e.g. BSD/macOS dev box) instead of hard-erroring at plant() with a confusing
+# "invalid date format".
+if ! stat -c%Y "$TMP" >/dev/null 2>&1 || ! touch -d '1 second ago' "$TMP/.probe" 2>/dev/null; then
+  echo "SKIP: GNU coreutils (stat -c / touch -d relative) required — non-GNU host"
+  exit 0
+fi
+rm -f "$TMP/.probe"
+
+# --- Stand up upstream + local bare clone (mirrors the soleur bare-repo layout,
+# same pattern as create-from-origin-main.test.sh) ---
+UPSTREAM="$TMP/upstream.git"
+git init --bare -b main "$UPSTREAM" >/dev/null
+SEED="$TMP/seed"
+git clone "$UPSTREAM" "$SEED" >/dev/null 2>&1
+( cd "$SEED" && git -c user.email=t@t -c user.name=t commit --allow-empty -m seed >/dev/null && git push origin main >/dev/null 2>&1 )
+rm -rf "$SEED"
+
+LOCAL="$TMP/local.git"
+git init --bare -b main "$LOCAL" >/dev/null
+( cd "$LOCAL" && git remote add origin "$UPSTREAM" && git fetch --no-tags origin main:main >/dev/null 2>&1 )
+
+# For a bare repo, `ensure_bare_config` resolves git_dir == GIT_ROOT (the bare
+# dir itself), so the config locks live directly under $LOCAL.
+GIT_DIR="$LOCAL"
+
+# --- Source the script to unit-test sweep_stale_git_locks() directly. The
+# script's BASH_SOURCE guard (worktree-manager.sh:1490) suppresses main() when
+# sourced. The script sets `set -euo pipefail`; disable errexit afterward so the
+# harness's if/else assertion style behaves like the sibling tests. ---
+cd "$LOCAL"
+# shellcheck source=/dev/null
+source "$WM"
+set +e
+
+# Plant a lock file with a specific mtime. $2 = seconds in the PAST.
+plant() { : > "$GIT_DIR/$1"; touch -d "$2 seconds ago" "$GIT_DIR/$1"; }
+present() { [[ -f "$GIT_DIR/$1" ]]; }
+
+# --- AC1: aged config.lock removed ---
+plant config.lock 120
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if present config.lock; then
+  fail "AC1: aged config.lock was NOT removed"
+else
+  pass "AC1: aged config.lock removed"
+fi
+
+# --- AC2: fresh config.worktree.lock preserved ---
+: > "$GIT_DIR/config.worktree.lock"   # mtime = now
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if present config.worktree.lock; then
+  pass "AC2: fresh config.worktree.lock preserved (age < threshold)"
+else
+  fail "AC2: fresh config.worktree.lock was WRONGLY removed"
+fi
+rm -f "$GIT_DIR/config.worktree.lock"
+
+# --- AC3: per-file age discrimination in one run — aged config.lock removed,
+# fresh config.worktree.lock preserved (fails against both a no-op and an
+# over-broad "delete every lock" impl) ---
+plant config.lock 120
+: > "$GIT_DIR/config.worktree.lock"
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if ! present config.lock && present config.worktree.lock; then
+  pass "AC3: aged config.lock removed AND fresh config.worktree.lock preserved in one run"
+else
+  fail "AC3: mixed-age sweep wrong (config.lock present=$(present config.lock && echo y || echo n), config.worktree.lock present=$(present config.worktree.lock && echo y || echo n))"
+fi
+rm -f "$GIT_DIR/config.worktree.lock"
+
+# --- AC3b: index.lock / HEAD.lock are OUT of scope — even aged instances are
+# preserved (on a non-bare git_dir these are LIVE working-tree locks; removing
+# one mid-op would tear the tenant's index — and they never block config writes) ---
+plant index.lock 120
+plant HEAD.lock 120
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if present index.lock && present HEAD.lock; then
+  pass "AC3b: aged index.lock/HEAD.lock preserved (deliberately out of sweep scope)"
+else
+  fail "AC3b: index.lock/HEAD.lock were swept (should be out of scope)"
+fi
+rm -f "$GIT_DIR/index.lock" "$GIT_DIR/HEAD.lock"
+
+# --- AC4: clock-skew guard — future-dated lock preserved (negative age = fresh) ---
+: > "$GIT_DIR/config.lock"
+touch -d "+120 seconds" "$GIT_DIR/config.lock"
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if present config.lock; then
+  pass "AC4: future-dated lock preserved (clock-skew guard)"
+else
+  fail "AC4: future-dated lock was WRONGLY removed"
+fi
+rm -f "$GIT_DIR/config.lock"
+
+# --- AC6: sweep clears an aged config.lock so a real git config write succeeds
+# (the exact prod EEXIST symptom, at the unit level — discriminating, not vacuous) ---
+plant config.lock 120
+sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null
+if git config --file "$GIT_DIR/config" test.key val >/dev/null 2>&1 \
+   && [[ "$(git config --file "$GIT_DIR/config" test.key 2>/dev/null)" == "val" ]]; then
+  pass "AC6: aged config.lock swept → git config write succeeds (no EEXIST)"
+else
+  fail "AC6: git config write FAILED after sweep (config.lock not cleared?)"
+fi
+git config --file "$GIT_DIR/config" --unset test.key 2>/dev/null
+
+# --- AC7: no-op is safe under `set -e` (empty lock set + missing dir) ---
+rm -f "$GIT_DIR"/*.lock 2>/dev/null
+if ( set -e; sweep_stale_git_locks "$GIT_DIR" 60 >/dev/null ); then
+  pass "AC7a: no-op sweep exits 0 under set -e (empty lock set)"
+else
+  fail "AC7a: no-op sweep aborted under set -e"
+fi
+if ( set -e; sweep_stale_git_locks "$TMP/does-not-exist" 60 >/dev/null ); then
+  pass "AC7b: sweep on missing dir exits 0 under set -e"
+else
+  fail "AC7b: sweep on missing dir aborted under set -e"
+fi
+
+# --- AC5: black-box self-heal wiring — an aged config.lock is swept when
+# cleanup-merged (the session-start preamble path) runs through ensure_bare_config ---
+: > "$GIT_DIR/config.lock"; touch -d "120 seconds ago" "$GIT_DIR/config.lock"
+( cd "$LOCAL" && bash "$WM" --yes cleanup-merged >"$TMP/cm.log" 2>&1 ) || true
+if present config.lock; then
+  fail "AC5: config.lock survived cleanup-merged (ensure_bare_config wiring; log: $(cat "$TMP/cm.log"))"
+else
+  pass "AC5: aged config.lock swept via cleanup-merged (ensure_bare_config wiring)"
+fi
+
+echo
+echo "=== Results ==="
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+[[ "$FAIL" -eq 0 ]] || exit 1
+exit 0

package/skills/go/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: go
+description: This skill is the unified entry point that classifies intent and routes to the right workflow skill
+argument-hint: "[what you want to do]"
+# `/soleur:go` also ships as plugins/soleur/commands/go.md. Claude Code loads
+# plugin commands AND plugin skills into one slash menu, so without this the name
+# renders twice. `user-invocable: false` leaves the menu row to the command while
+# keeping this skill model-invocable — Skill(soleur:go) must keep working.
+# Grok 1.0.40 validates plugin commands/ but does not register them as slash
+# commands. Do not flip this flag to expose the go row there — that re-duplicates
+# Claude Code. The Grok slash row is `.grok/commands/go.md` (symlink onto
+# commands/go.md).
+user-invocable: false
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+**Which harness this body is for.** Everything below the next heading is the **Devin CLI**
+entry-point shim: it addresses itself as the `/soleur:go` slash command, resolves paths through
+`${CLAUDE_PLUGIN_ROOT}`, and names Devin's own adapter tools. The Grok block above says to run
+this document to completion; read the two together, because on a harness other than Devin the
+body below is not the thing to run:
+
+- **Claude Code** — this skill is `user-invocable: false` and the operator-facing row is
+  `plugins/soleur/commands/go.md`. Read that file and act as its handler.
+- **Grok Build** — the slash row is `.grok/commands/go.md`, which resolves to the same
+  `commands/go.md`. Read that file and act as its handler. Do NOT detect the harness as Devin,
+  and do not use `run_subagent`; Grok's spawn tool is `spawn_subagent` with hyphenated agent ids.
+- **Codex** — `codex/skills/go/SKILL.md` is the front door. Read `commands/go.md` and act as
+  its handler, translating tools through `codex/INSTRUCTIONS.md` §Tools.
+
+In every case the AUTHORITY is `commands/go.md`; the harness shims differ only in how they
+address the operator and which tool names they use.
+
+The authority's first Sharp Edge covers a brief: its "ask the operator" / "OPEN DECISION" wording on a technical fork is the trigger to spawn the CTO, never a reason to ask ([technical-ruling-delegation.md](${CLAUDE_PLUGIN_ROOT}/skills/brainstorm-techniques/references/technical-ruling-delegation.md)).
+
+# /soleur:go (Devin CLI entry point)
+
+You are the `/soleur:go` slash command for the Soleur plugin on Devin CLI.
+
+The user's request is the text that follows `/soleur:go`. Treat that text as `$ARGUMENTS`.
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/commands/go.md`.
+2. Follow every instruction in that file as if you were the `/soleur:go` handler.
+3. Where the file uses `$ARGUMENTS` or `#$ARGUMENTS`, substitute the user's actual request.
+4. When routing to a skill, use the Devin harness adapter: invoke the `/soleur:<skill>` slash command with the user's request as arguments.
+5. When routing to an agent, use the `run_subagent` tool with the agent id and the user's request as the prompt.
+6. Do not improvise workflow steps. Route through the named skill or agent.

package/skills/growth/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: growth
+description: "This skill should be used when performing content strategy analysis, keyword research, content auditing, content gap analysis, or AI agent consumability auditing. Sub-commands: auditing, planning, applying fixes."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Growth Strategy
+
+Analyze content for keyword alignment, plan content to capture search traffic, audit AI agent consumability, and apply content fixes. This skill delegates to the soleur:marketing:growth-strategist agent for content-level analysis and execution.
+
+## Sub-commands
+
+| Command | Description |
+|---------|-------------|
+| `growth audit <url-or-path>` | Audit existing content for keyword alignment and search intent match |
+| `growth fix <path>` | Audit and apply keyword/copy/AEO fixes to local source files |
+| `growth plan <topic> [--site <url-or-path>] [--competitors url1,url2]` | Research keywords, analyze gaps, and produce a prioritized content plan |
+| `growth aeo <url-or-path>` | Audit content for GEO/AEO optimization (source citations, statistics, conversational readiness, FAQ structure, citation quality) |
+
+If no sub-command is provided, display the table above and ask which sub-command to run.
+
+---
+
+## Sub-command: audit
+
+Analyze existing site content for keyword alignment, search intent match, and readability. Produces a report with issues and rewrite suggestions.
+
+### Steps
+
+1. Parse the argument as a URL or local file/directory path. URLs start with `http://` or `https://`. Everything else is a local path.
+
+2. Check for brand guide:
+
+   ```bash
+   if [[ -f "knowledge-base/marketing/brand-guide.md" ]]; then
+     echo "Brand guide found. Will use for voice alignment."
+   fi
+   ```
+
+3. Launch the soleur:marketing:growth-strategist agent via the Task tool:
+
+   ```
+   Task soleur:marketing:growth-strategist: "Audit the content at <url-or-path> for keyword alignment,
+   search intent match, and readability. <if brand guide exists: Also read
+   knowledge-base/marketing/brand-guide.md and align rewrite suggestions with the brand voice.>
+   Produce a structured report with per-page analysis, issues found, and rewrite suggestions.
+   Use WebFetch for URLs or Read/Glob for local paths."
+   ```
+
+4. Present the agent's report to the user.
+
+---
+
+## Sub-command: fix
+
+Audit existing content and apply fixes to local source files. Combines analysis and execution in one pass, following the `seo-aeo fix` pattern.
+
+### Steps
+
+1. Parse the argument as a local file or directory path. If the argument starts with `http://` or `https://`, display: "growth fix works on local files only. For URL analysis, use `growth audit`." Stop execution.
+
+2. Check for brand guide:
+
+   ```bash
+   if [[ -f "knowledge-base/marketing/brand-guide.md" ]]; then
+     echo "Brand guide found. Will validate rewrites against brand voice."
+   fi
+   ```
+
+3. Launch the soleur:marketing:growth-strategist agent via the Task tool:
+
+   ```
+   Task soleur:marketing:growth-strategist: "Audit the content at <path> for keyword alignment,
+   search intent match, readability, and GEO/AEO gaps. For each issue found, apply
+   a fix to the source files. Read each file before editing.
+   <if brand guide exists: Read knowledge-base/marketing/brand-guide.md and
+   validate all rewrites against the brand voice before applying.>
+   After all fixes, build the site to verify changes compile.
+   Report what was changed per file."
+   ```
+
+4. Present the agent's report showing changes made.
+5. If the build failed, show the error and suggest: "Run `git checkout -- <file>` to revert changes, or fix the build error manually."
+
+---
+
+## Sub-command: plan
+
+Research keywords, analyze content gaps, and produce a prioritized content plan. This is a self-contained workflow that combines keyword research, gap analysis, and planning.
+
+### Steps
+
+1. Parse arguments:
+   - `<topic>` (required): the topic or keyword space to research
+   - `--site <url-or-path>` (optional): the user's existing site for gap analysis
+   - `--competitors url1,url2` (optional): competitor URLs for comparison
+
+2. Check for brand guide (same as audit step 2).
+
+3. Launch the soleur:marketing:growth-strategist agent via the Task tool:
+
+   ```
+   Task soleur:marketing:growth-strategist: "Create a content plan for the topic '<topic>'.
+
+   1. Research keywords related to this topic using WebSearch. Classify each by search
+      intent (informational, navigational, commercial, transactional) and relevance.
+
+   2. <if --site provided: Analyze the existing content at <site> to identify gaps --
+      topics where the site has no coverage or only partial coverage.>
+
+   3. <if --competitors provided: Fetch competitor sites at <urls> via WebFetch and
+      compare their content coverage against the target keywords. Skip unreachable
+      competitors and note them.>
+
+   4. Produce a prioritized content plan: P1 (high impact), P2 (medium), P3 (future).
+      Each piece should include content type, target keywords, search intent, and outline.
+
+   <if brand guide exists: Read knowledge-base/marketing/brand-guide.md and align
+   keyword relevance and content priorities with the brand positioning.>"
+   ```
+
+4. Present the agent's report to the user.
+
+---
+
+## Sub-command: aeo
+
+Audit content for AI agent consumability at the content level. Checks whether AI models can accurately extract, cite, and quote the content.
+
+### Steps
+
+1. Parse the argument as a URL or local path (same heuristic as audit).
+
+2. Launch the soleur:marketing:growth-strategist agent via the Task tool:
+
+   ```
+   Task soleur:marketing:growth-strategist: "Audit the content at <url-or-path> for GEO/AEO optimization.
+   Check source citation presence, statistics/specificity, conversational readiness,
+   FAQ structure quality, definition extractability, summary quality, and
+   citation-friendly paragraph structure.
+   Do NOT check JSON-LD, meta tags, sitemaps, or llms.txt format -- those belong to
+   the soleur:marketing:seo-aeo-analyst agent. Focus only on content-level checks.
+   Use WebFetch for URLs or Read/Glob for local paths."
+   ```
+
+3. Present the agent's report to the user.
+4. If technical AEO checks are also needed, suggest: "Run `seo-aeo audit` for technical SEO and AEO checks (JSON-LD, meta tags, llms.txt)."
+
+---
+
+## Important Guidelines
+
+- Each sub-command is independent. No sub-command requires a prior run of another.
+- The `plan` sub-command performs its own keyword research internally -- no need to run a separate research step first.
+- The `audit`, `plan`, and `aeo` sub-commands produce inline output only. The `fix` sub-command modifies source files directly.
+- The soleur:marketing:growth-strategist agent handles content-level analysis. For technical SEO (meta tags, JSON-LD, sitemaps, llms.txt), direct users to the `seo-aeo` skill instead.
+- For generating new articles from content plans, direct users to the `content-writer` skill.

package/skills/harvest-debt/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: harvest-debt
+description: "This skill should be used when harvesting inline SOLEUR-DEBT: markers from the codebase into a ledger grouped by file, flagging markers with no upgrade trigger."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Harvest Inline Deferral Markers
+
+Read-only harvester for inline `SOLEUR-DEBT:` deferral markers. It makes the
+deliberate shortcuts left in code grep-discoverable so a deferral cannot quietly
+become permanent. It complements — never duplicates — the reactive
+[technical-debt ledger](../../../../knowledge-base/project/learnings/technical-debt/README.md):
+
+- **harvest-debt (this skill)** — SURFACE inline markers where they live, in code.
+- [soleur:compound](../compound-capture/SKILL.md) — PROMOTE a worth-tracking marker into a ledger entry.
+- [soleur:resolve-debt](../resolve-debt/SKILL.md) — CLOSE a ledger entry with a linked GitHub issue.
+
+It writes nothing and closes nothing; promotion and closure stay deliberate acts.
+
+## The marker convention
+
+A deliberate shortcut is annotated inline, in a code comment, with the ceiling it
+tops out at and the observable trigger that says "do the real thing now":
+
+```text
+// SOLEUR-DEBT: <ceiling>; <upgrade trigger>
+```
+
+- Use the all-caps `SOLEUR-DEBT:` marker — never a bare `soleur:` prefix, which
+  collides with skill references like `soleur:go` throughout the docs.
+- The text before the first `;` is the **ceiling** (the shortcut / current limit);
+  the text after is the **upgrade trigger**.
+- Example: `// SOLEUR-DEBT: global lock; switch to per-account locks if throughput matters`.
+- A marker with no `;`-delimited trigger is the rot-prone case — the harvest flags
+  it `no-trigger`.
+
+This marker is the canonical, grep-discoverable form of the in-place deferral that
+the `wg-when-deferring-a-capability-create-a` gate prefers over filing speculative backlog
+issues. Document a deferral here, in code, and harvest makes it visible without
+converting every shortcut into phantom backlog.
+
+## Run
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/harvest-debt/scripts/harvest-debt.sh"
+```
+
+Run from the repo root. The harvester ([harvest-debt.sh](./scripts/harvest-debt.sh)):
+
+1. Greps tracked source for `SOLEUR-DEBT:` markers.
+2. Groups hits by file and splits each on the first `;` into ceiling + trigger.
+3. Flags any marker with no trigger as `no-trigger`.
+4. Prints a markdown report ending with `<N> markers, <M> with no trigger.`, or
+   `No SOLEUR-DEBT markers found.` when the tree is clean.
+
+`--help` prints usage. The script is idempotent and read-only.
+
+## After harvesting
+
+For each surfaced marker, decide:
+
+- **Worth tracking** → run [soleur:compound](../compound-capture/SKILL.md) to promote it
+  into a `technical-debt/` ledger entry, then [soleur:resolve-debt](../resolve-debt/SKILL.md)
+  to close it with a linked issue once the upgrade trigger fires.
+- **`no-trigger`** → add the missing upgrade trigger to the comment, or delete the
+  marker if the shortcut is now permanent and accepted.
+
+## Scope (and its one limitation)
+
+The harvest scans CODE comments only. Prose (`*.md` — the convention doc, plans,
+specs, SKILL bodies), `node_modules`, and build output (`_site`, `dist`, `*.min.*`)
+are excluded so the marker DEFINITION never self-reports as debt. This is a **path
+denylist, not a semantic check**: a `SOLEUR-DEBT:` literal placed in a non-`.md`
+source file purely as documentation would still be reported. Keep marker examples
+in markdown.

package/skills/harvest-debt/scripts/harvest-debt.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# harvest-debt.sh — surface inline SOLEUR-DEBT deferral markers as a ledger.
+#
+# Greps tracked SOURCE for `SOLEUR-DEBT:` markers, groups hits by file, splits
+# each on the first `;` into ceiling + upgrade-trigger, and flags any marker
+# with no trigger as `no-trigger` (the rot-prone case). Read-only: it writes
+# nothing and closes nothing — promotion into the ledger is /soleur:compound,
+# closure is /soleur:resolve-debt.
+#
+# Scope: CODE comments only. `*.md` prose (the convention doc, plans, specs,
+# SKILL bodies) is excluded by design so the marker DEFINITION never self-reports
+# as debt — a path denylist, not a semantic check (see SKILL.md "Scope").
+#
+# Usage: harvest-debt.sh [--help]   (run from the repo root)
+# Exit: 0 = clean (markers reported or none found); 2 = usage error.
+set -euo pipefail
+
+readonly MARKER="SOLEUR-DEBT:"
+
+usage() {
+  cat <<'EOF'
+harvest-debt.sh — list inline SOLEUR-DEBT deferral markers, grouped by file.
+
+Usage:
+  harvest-debt.sh           Harvest markers from the current git repo.
+  harvest-debt.sh --help    Show this help.
+
+A marker reads `// SOLEUR-DEBT: <ceiling>; <upgrade trigger>`. Markers with no
+`;`-delimited trigger are flagged `no-trigger`. Read-only — promote worth-tracking
+markers with /soleur:compound, close them with /soleur:resolve-debt.
+EOF
+}
+
+main() {
+  case "${1:-}" in
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    "") ;;
+    *)
+      echo "harvest-debt: unknown argument '$1'" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "harvest-debt: not inside a git work tree" >&2
+    exit 2
+  fi
+
+  # Anchor at the repo root so the exclude pathspecs (which are repo-root-relative)
+  # match regardless of the caller's subdirectory — enforces the "run from root"
+  # contract instead of merely documenting it.
+  cd "$(git rev-parse --show-toplevel)" || exit 2
+
+  # git grep already skips untracked paths (node_modules, .git). Exclude prose
+  # (*.md), this skill's own dir (its marker literals are definitions), and build
+  # output. git grep exits 1 on no match under pipefail — tolerate with `|| true`.
+  local hits
+  hits="$(
+    git grep -nI -F -e "$MARKER" -- \
+      ':(exclude)*.md' \
+      ':(exclude)plugins/soleur/skills/harvest-debt' \
+      ':(exclude)*.min.*' \
+      ':(exclude,glob)**/node_modules/**' \
+      ':(exclude,glob)**/_site/**' \
+      ':(exclude,glob)**/dist/**' \
+      2>/dev/null || true
+  )"
+
+  if [[ -z "$hits" ]]; then
+    echo "No SOLEUR-DEBT markers found."
+    exit 0
+  fi
+
+  printf '%s\n' "$hits" | awk -v marker="$MARKER" '
+    BEGIN { total = 0; untriggered = 0; prev = "" }
+    {
+      # git grep -n emits "<file>:<lineno>:<content>". Anchor on the ":<digits>:"
+      # boundary (lineno is always numeric) so a colon WITHIN the path does not
+      # mis-peel file/lineno. Skip any line lacking that boundary.
+      if (!match($0, /:[0-9]+:/)) next
+      file = substr($0, 1, RSTART - 1)
+      rest = substr($0, RSTART + 1)
+      j = index(rest, ":"); lineno = substr(rest, 1, j - 1); content = substr(rest, j + 1)
+
+      m = index(content, marker)
+      after = substr(content, m + length(marker))
+      gsub(/^[ \t]+/, "", after); gsub(/[ \t]+$/, "", after)
+
+      s = index(after, ";")
+      if (s > 0) { ceiling = substr(after, 1, s - 1); trigger = substr(after, s + 1) }
+      else { ceiling = after; trigger = "" }
+      gsub(/[ \t]+$/, "", ceiling)
+      gsub(/^[ \t]+/, "", trigger); gsub(/[ \t]+$/, "", trigger)
+
+      if (file != prev) { printf "\n## %s\n", file; prev = file }
+      if (trigger == "") {
+        printf "- L%s — ceiling: %s — **no-trigger**\n", lineno, ceiling
+        untriggered++
+      } else {
+        printf "- L%s — ceiling: %s — trigger: %s\n", lineno, ceiling, trigger
+      }
+      total++
+    }
+    END {
+      printf "\n%d marker%s, %d with no trigger.\n", total, (total == 1 ? "" : "s"), untriggered
+    }
+  '
+}
+
+main "$@"