docs(archdev-skill): refresh installed hooks from bootstrap; describe nudge hooks

archdev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archdev
-description: Core ArchDev workflow — use for anything involving ArchDev. Covers archdev CLI setup, upgrade, login, and model access; archdev.json configuration and validation (check); repo onboarding and readiness (repo status, repo init); mapping a repo's plans, tasks, agents, and review workflow into the activity taxonomy (repo map); session start/stop hooks (repo hook setup); reporting build events as unstructured notes or schema-validated payloads (archdev log post, log post --event); reading and searching the team room for prior lessons (log messages, log search); publishing team lifecycle posts — start, lesson, abandoned, done, handoff, question (log --kind); and observing agent activity (repo monitor). Load at session start whenever the archdev CLI is installed, the repo contains archdev.json, or the task touches plans, tasks, sessions, commits, PRs, or harness hooks.
+description: Core ArchDev workflow — use for anything involving ArchDev. Covers archdev CLI setup, upgrade, login, and model access; archdev.json configuration and validation (check); repo onboarding and readiness (repo status, repo init); mapping a repo's plans, tasks, agents, and review workflow into the activity taxonomy (repo map); harness monitor hooks (repo hook setup); reporting build events as unstructured notes or schema-validated payloads (archdev log post, log post --event); reading and searching the team room for prior lessons (log messages, log search); publishing team lifecycle posts — start, lesson, abandoned, done, handoff, question (log --kind); and observing agent activity (repo monitor). Load at session start whenever the archdev CLI is installed, the repo contains archdev.json, or the task touches plans, tasks, sessions, commits, PRs, or harness hooks.
 ---
 
 # ArchDev
@@ -60,8 +60,9 @@ Read [map.md](references/map.md). Goal: repo opted in via `archdev.json`
 (`repo init` when missing; personal overrides stay in gitignored
 `archdev.local.json`), plus the `activity` taxonomy describing how this
 repo plans, codes, reviews, and takes instruction. End by installing
-start + stop hooks (`repo hook setup`) so session coverage starts
-immediately.
+the monitor hooks (`repo hook setup`) so session coverage starts
+immediately. Bootstrap keeps installed hooks on the CLI's wiring
+(`repo hook setup --refresh`).
 
 ## 3. Monitor
 

archdev/references/map.md

@@ -1,7 +1,7 @@
 # Map
 
 Goal: opt the repo into ArchDev and record how it works in `archdev.json`
-under the `activity` key, then install start + stop hooks.
+under the `activity` key, then install the monitor hooks.
 
 ## 1. Init
 
@@ -79,14 +79,24 @@ after editing.
 
 ## 4. Install hooks (final map step)
 
-Both hooks, now — session coverage starts immediately:
+Install now — session coverage starts immediately:
 
 ```sh
-"$archdev" repo hook setup [--harness claude|codex|grok] [--force]
+"$archdev" repo hook setup [--harness claude|codex|grok|archdev] [--force]
 ```
 
-Without `--harness`, covers every installed harness (config-dir presence
-= installed); warns when none is found — pass `--harness <name>` to
-install anyway. `--uninstall` removes them. Harnesses outside
-`claude|codex|grok`: hand-author start/stop entries invoking `repo hook
-start|stop`. Verify both hooks per harness (`repo status` checks this).
+Installs SessionStart, UserPromptSubmit, PostToolUse and Stop (Grok: no
+UserPromptSubmit). Without `--harness`, covers every installed harness
+(config-dir presence = installed); warns when none is found — pass
+`--harness <name>` to install anyway. `--uninstall` removes them.
+Harnesses outside that list: hand-author entries invoking `repo hook
+start|prompt|post-tool|stop --spec <N>` (copy `N` from `repo hook setup
+--help`). Verify with `repo status`: it reports missing hooks and hooks
+from an older `--spec` as stale.
+
+Each installed command carries `--spec N`, the hook wiring version of the
+CLI that wrote it. This skill's bootstrap runs `repo hook setup --refresh`
+after checking the CLI, which updates only harnesses that already have
+archdev hooks. Setup refuses when the `archdev` on PATH (what hooks run)
+is older than the CLI running setup; upgrade or fix PATH rather than
+passing `--force`.

archdev/references/monitor.md

@@ -19,6 +19,13 @@ per-event extraction schemas, and the report commands. Without hooks,
 run `"$archdev" repo monitor bootstrap` at session start for the same
 block. The static checklist below is the same shape for reference.
 
+With hooks installed, a tool call that looks like a watched event (commit,
+push, `gh pr …`, `archdev tasks …`, a plan edit) is followed by an
+`ArchDev monitor:` note naming the likely event and extractor. Report it
+if it is a real hit; `archdev log post --event <type>` clears it. A note
+left unreported is repeated once at your next prompt. The hooks never
+block a stop.
+
 ## Team room
 
 The organization room is the team's shared memory: lifecycle posts and
@@ -236,7 +243,7 @@ host already automates part of this workflow:
 
 When an event fires reliably across sessions, say so in your report:
 high-signal events (`commit.*`, `pr.*`) graduate from model attention
-into the stop hook, and leave the self-check block. The block shrinks as
+into hooks that post them directly, and leave the self-check block. The block shrinks as
 the taxonomy proves itself.
 
 ## Coexistence (invariants)

archdev/scripts/bootstrap.ps1

@@ -65,4 +65,21 @@ if (-not (Test-Path -LiteralPath $archdev -PathType Leaf)) {
 & $archdev --version *> $null
 if ($LASTEXITCODE -ne 0) { throw "ArchDev version verification failed" }
 if (-not (Test-Skill $archdev)) { throw "Installed ArchDev does not provide Agents, provider, and repo commands" }
+
+# Bring installed ArchDev harness hooks up to this CLI's hook wiring. Only
+# harnesses that already have archdev hooks change, and a failure (for example
+# an older archdev earlier on PATH) is reported without blocking the skill.
+# Its stderr goes straight to the console; only stdout is relayed, because
+# merging stderr into the pipeline under ErrorActionPreference=Stop throws.
+try {
+    $hookHelp = (& $archdev repo hook setup --help 2>$null) -join "`n"
+    if ($hookHelp -match "--refresh") {
+        & $archdev repo hook setup --refresh | ForEach-Object { [Console]::Error.WriteLine($_) }
+        if ($LASTEXITCODE -ne 0) {
+            [Console]::Error.WriteLine("Could not refresh ArchDev hooks; see above, then run: archdev repo hook setup")
+        }
+    }
+} catch {
+    [Console]::Error.WriteLine("Could not refresh ArchDev hooks: $_")
+}
 Write-Output $archdev

archdev/scripts/bootstrap.sh

@@ -98,4 +98,13 @@ supports_skill "$executable" || {
   printf 'Installed ArchDev does not provide Agents, provider, and repo commands.\n' >&2
   exit 1
 }
+
+# Bring installed ArchDev harness hooks up to this CLI's hook wiring. Only
+# harnesses that already have archdev hooks change, and a failure (for example
+# an older archdev earlier on PATH) is reported without blocking the skill.
+hook_help="$("$executable" repo hook setup --help 2>/dev/null || true)"
+if [[ "$hook_help" == *"--refresh"* ]]; then
+  "$executable" repo hook setup --refresh >&2 ||
+    printf 'Could not refresh ArchDev hooks; see above, then run: archdev repo hook setup\n' >&2
+fi
 printf '%s\n' "$executable"

tasks/scripts/bootstrap.ps1

@@ -46,4 +46,21 @@ if (-not (Test-Path -LiteralPath $archdev -PathType Leaf)) {
 if ($LASTEXITCODE -ne 0) { throw "ArchDev version verification failed" }
 & $archdev tasks review update --help *> $null
 if ($LASTEXITCODE -ne 0) { throw "Installed ArchDev does not provide Tasks web review commands" }
+
+# Bring installed ArchDev harness hooks up to this CLI's hook wiring. Only
+# harnesses that already have archdev hooks change, and a failure (for example
+# an older archdev earlier on PATH) is reported without blocking the skill.
+# Its stderr goes straight to the console; only stdout is relayed, because
+# merging stderr into the pipeline under ErrorActionPreference=Stop throws.
+try {
+    $hookHelp = (& $archdev repo hook setup --help 2>$null) -join "`n"
+    if ($hookHelp -match "--refresh") {
+        & $archdev repo hook setup --refresh | ForEach-Object { [Console]::Error.WriteLine($_) }
+        if ($LASTEXITCODE -ne 0) {
+            [Console]::Error.WriteLine("Could not refresh ArchDev hooks; see above, then run: archdev repo hook setup")
+        }
+    }
+} catch {
+    [Console]::Error.WriteLine("Could not refresh ArchDev hooks: $_")
+}
 Write-Output $archdev

tasks/scripts/bootstrap.sh

@@ -82,4 +82,13 @@ fi
   printf 'Installed ArchDev does not provide Tasks web review commands.\n' >&2
   exit 1
 }
+
+# Bring installed ArchDev harness hooks up to this CLI's hook wiring. Only
+# harnesses that already have archdev hooks change, and a failure (for example
+# an older archdev earlier on PATH) is reported without blocking the skill.
+hook_help="$("$executable" repo hook setup --help 2>/dev/null || true)"
+if [[ "$hook_help" == *"--refresh"* ]]; then
+  "$executable" repo hook setup --refresh >&2 ||
+    printf 'Could not refresh ArchDev hooks; see above, then run: archdev repo hook setup\n' >&2
+fi
 printf '%s\n' "$executable"