devflow-kit 3.8.0 → 3.10.0

package/src/assets/scripts/hooks/assets/implement-installed

@@ -0,0 +1 @@
+# devflow writes this file while devflow-implement is installed. The session preamble only checks that the file exists.

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -1,22 +1,24 @@
 --- ORCHESTRATOR CHARTER ---
 You are the orchestrator of this session: you coordinate, agents produce.
 
-Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it, with one bounded exception: the main thread may run only a single git, gh or script command whose output stays under about 40 lines, and never a diff, log or test run.
+Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it, with one bounded exception: the main thread may run a single git, gh or script command whose output stays under about 40 lines, never a diff, log or test run.
 
-Routing (Agent tool) — pick the roster agent that fits the work:
+Routing (Agent tool), by kind of work:
 - Search and listing: Explore. Codebase orientation: Skim.
-- Execution against a spec: Code (write code to a plan; open the prompt with `OPERATION: <mode>` — `issue-fix` for pre-classified review issues, else `implement`), Refactor (a given mechanical change: "rename X to Y everywhere", moves, boilerplate; `OPERATION: edit`), Polish (judgment pass for clarity that keeps behaviour: "make this code cleaner"), Validate (build, typecheck, lint, test), Git (git/GitHub).
-- Bug fix: Code (`OPERATION: implement`; `issue-fix` only for Triage-classified review issues). Fix: gate failures only (`validation-fix`, `alignment-fix`, `qa-fix`, `ci-fix`).
-- Analysis, design, research: Design, Research, Review, Triage (validate review issues against blast-radius matrix).
-- Real-scale work matching a workflow: invoke the full skill instead — devflow:implement, devflow:plan, devflow:research, devflow:explore, devflow:debug (all debug work, never the Debug agent), devflow:code-review, devflow:resolve.
+- Execution against a spec: Code (write code to a plan; open the prompt with `OPERATION: <mode>`: `issue-fix` for pre-classified review issues, else `implement`), Refactor (a given mechanical change: renames, moves, boilerplate; `OPERATION: edit`), Polish (clarity pass that keeps behaviour), Validate (build, typecheck, lint, test), Git (git/GitHub).
+- Checks: Harden (self-review that fixes, after Code), Evaluate (alignment with request and plan), Test (scenario QA on acceptance criteria; never fixes). Gate failures: Fix (`OPERATION:` `validation-fix`, `alignment-fix`, `qa-fix` or `ci-fix`), else Code (`OPERATION: implement`).
+- Bug fix: Code (`OPERATION: implement`). All debug work (root cause of a reported bug): devflow:debug, else Explore investigates and Code fixes; never the Debug agent.
+- Analysis, design, research: Design, Research, Review, Triage (validate review issues), Synthesize (many or large reports; open its prompt with `Mode: <mode>`).
+- A new knowledge base, only if the user asks: Knowledge (slug, name, directories).
+- Real-scale work matching a workflow: invoke the full skill instead: devflow:implement, devflow:plan, devflow:research, devflow:explore, devflow:code-review, devflow:resolve, devflow:bug-analysis (hunt bugs in a branch before merge).
 - Anything else: the closest roster agent, never general-purpose.
 
-Stays mainline (judgment work): conversation, decisions, routing, synthesizing agent reports, answers already in loaded context, one targeted Read to scope a delegation.
+Stays mainline (judgment work): conversation, decisions, routing, combining a few agent reports, answers already in loaded context, one targeted Read to scope a delegation.
 
 Operating rules:
-- Decompose mainline. Subagents cannot spawn subagents — you own task breakdown, then delegate leaf tasks.
+- Decompose mainline. Subagents cannot spawn subagents: you own task breakdown, then delegate leaf tasks.
 - Subagents see none of this conversation. Make every delegation self-contained: goal, constraints, relevant session decisions and facts, exact paths. A deliverable that draws on the conversation (issue, PR, report) needs its substance in the prompt, not a pointer.
-- Report cap: ask every direct delegation for a final report of at most about 1,500 tokens — findings, paths and verdicts, not file dumps.
+- Report cap: ask every direct delegation for a final report of at most about 1,500 tokens: findings, paths and verdicts, not file dumps.
 - Parallelize independent delegations in one message. Git operations stay sequential.
-- Feature knowledge (direct delegations only — workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass each matching KB's one to three most relevant `## Rules` bullets (verbatim, IDs included; a KB without Rules: Anti-Patterns or Gotchas entries, cited by section), its path and its `##` heading index as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
-- Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with no arguments — the plan is already in this conversation. Do not pause to ask.
+- Feature knowledge (direct delegations only; workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass each matching KB's one to three most relevant `## Rules` bullets (verbatim, IDs included; a KB without Rules: Anti-Patterns or Gotchas entries, cited by section), its path and its `##` heading index as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
+- Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with no arguments: the plan is already in this conversation. Do not pause to ask.

package/src/assets/scripts/hooks/background-memory-update

@@ -29,6 +29,9 @@
 #               for the next run (D-QUEUE-NO-ORPHAN-DELETE)
 # No parser:    neither jq nor node on PATH → exits with no LLM run; the queue and any .processing batch are left in place
 # Parser fails: jq or node exits non-zero while it reads the queue or the batch → exits with no LLM run; the turns are kept
+# Paused area:  git tracks files in the memory folder, or a `.git` entry stands and git does not answer → exits with
+#               result=skip and no LLM run, and reads, claims, writes and notices nothing; asked at the start, and again
+#               after the run, where a late answer leaves the staged file unswapped and the batch in .processing
 
 set -e
 
@@ -128,6 +131,59 @@ source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 # The staged-path check, the settings JSON with the worker's Edit allow and deny rules, the
 # result line and the one-time notice (needs df_no_symlink_below from resolve-project-root).
 source "$SCRIPT_DIR/memory-permission" || { echo "background-memory-update: failed to source memory-permission" >&2; exit 1; }
+source "$SCRIPT_DIR/queue-append" || { echo "background-memory-update: failed to source queue-append" >&2; exit 1; }
+
+# --- The memory area check: git tracks files in the memory folder, or does not answer ---
+# A folder that git tracks holds the repository's content, not devflow's data. While git
+# tracks files in the memory folder of this checkout, or a `.git` entry stands and git does
+# not answer, the memory area is paused, and the worker reads and writes nothing there.
+# Sets DF_TRACKED_AREA_MEMORY to `tracked`, `untracked` or `unknown` for the project root in
+# $1: queue_tracked_area in git mode, run in a background subshell that answers by its exit
+# status (10 untracked, 11 tracked), so that a git that hangs can be cut and no file is made.
+# Every call asks git afresh: the second ask of a run must see what changed during the run.
+# The bound is DEVFLOW_BG_AREA_PROBE_SECS (default 5, at most 60; tests override it as they
+# do DEVFLOW_BG_WATCHDOG_SECS), kept by the watchdog's background-and-kill idiom: a SIGKILL
+# to the probe's process group (set -m) after a sleep, and a SIGKILL cancel of the watchdog,
+# so no exit trap runs in either subshell (the one `Run:` line, above). A probe that is
+# cut, or ends in any other status, reads `unknown`: the area stays paused. The notices of
+# memory-permission read this variable, so the worker leaves one only after this check has
+# asked and found the area free. Always returns 0.
+probe_memory_area() {
+  local _root="${1:-}" _secs _pid _wd_pid _status=1
+  DF_TRACKED_AREA_MEMORY="unknown"
+  _secs="${DEVFLOW_BG_AREA_PROBE_SECS:-5}"
+  case "$_secs" in
+    ''|*[!0123456789]*|????*) _secs=5 ;;
+  esac
+  if [ "$_secs" -lt 1 ] || [ "$_secs" -gt 60 ]; then _secs=5; fi
+  set -m
+  (
+    _QTA_ASKED_MEMORY=""
+    queue_tracked_area "$_root" memory git
+    case "$DF_TRACKED_AREA_MEMORY" in
+      untracked) exit 10 ;;
+      tracked) exit 11 ;;
+    esac
+    exit 12
+  ) </dev/null >/dev/null 2>&1 &
+  _pid=$!
+  set +m
+  (
+    sleep "$_secs"
+    kill -KILL -"$_pid" 2>/dev/null || true
+  ) </dev/null >/dev/null 2>&1 &
+  _wd_pid=$!
+  if wait "$_pid" 2>/dev/null; then _status=0; else _status=$?; fi
+  # SIGKILL, not SIGTERM, as for the other watchdogs: no trap can run in the subshell.
+  kill -KILL "$_wd_pid" 2>/dev/null || true
+  wait "$_wd_pid" 2>/dev/null || true
+  case "$_status" in
+    10) DF_TRACKED_AREA_MEMORY="untracked" ;;
+    11) DF_TRACKED_AREA_MEMORY="tracked" ;;
+  esac
+  return 0
+}
+
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 # One canonical root feeds every path below, the staged path in the prompt and in the
@@ -136,6 +192,7 @@ PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 PROJECT_ROOT_CANONICAL=$(cd -P -- "$PROJECT_ROOT" 2>/dev/null && pwd -P) || PROJECT_ROOT_CANONICAL=""
 if [ -z "$PROJECT_ROOT_CANONICAL" ]; then
   log "SKIP: project root could not be resolved; no LLM run"
+  probe_memory_area "$PROJECT_ROOT"
   memory_notice_write "$PROJECT_ROOT/.devflow/memory" "$PROJECT_ROOT" path
   exit 0
 fi
@@ -154,13 +211,23 @@ OK_FILE="$MEMORY_DIR/.last-refresh-ok"
 # have been disabled since spawn, or narrowed by a checkout that now carries a
 # `features.memory: false`). Same helper as every other memory/curation gate
 # (D-FEATURES-NARROW-ONLY, see queue-append).
-source "$SCRIPT_DIR/queue-append" || { echo "background-memory-update: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 if [ "$_QG_MEMORY" != "true" ]; then
   log "ABORT: memory disabled (disabled after spawn)"
   exit 0
 fi
 
+# --- Ask whether git tracks files in the memory folder ---
+# The area may have become tracked since the Stop hook spawned this worker. A paused area
+# ends the run here, before the binary is resolved, a link is checked, the lock is taken or
+# a batch is claimed: nothing is read, moved or written, and no notice is left. The run's
+# `Run:` line says skip.
+probe_memory_area "$PROJECT_ROOT"
+if [ "$DF_TRACKED_AREA_MEMORY" != "untracked" ]; then
+  log "SKIP: the memory area is paused (git tracks files in the memory folder, or did not answer); nothing read or written; no LLM run"
+  exit 0
+fi
+
 # --- Resolve claude binary ---
 CLAUDE_BIN=$(command -v claude 2>/dev/null || true)
 if [ -z "$CLAUDE_BIN" ]; then
@@ -1126,6 +1193,17 @@ case "$MEMORY_RESULT_DENIALS" in
   *) RESULT_DENIED="yes" ;;
 esac
 
+# The run took minutes, so the memory area is asked again before anything lands in the
+# folder. If git tracks files there now, or does not answer, nothing below runs: the staged
+# file is not checked, moved or removed, no stamp is touched, no denied run is counted and
+# no notice is left. The batch stays in .processing.
+probe_memory_area "$PROJECT_ROOT"
+if [ "$DF_TRACKED_AREA_MEMORY" != "untracked" ]; then
+  RUN_RESULT="skip"
+  log "SKIP: the memory area is paused (git tracks files in the memory folder, or did not answer); nothing swapped or stamped; the batch stays in .processing"
+  exit 0
+fi
+
 # A folder or a link at the staged path now was put there during the run: the path was
 # empty at the spawn. It is removed the way it is before a run (memory_staged_remove), and
 # the run ends as failed: the checks below find no staged file, and the batch stays for

package/src/assets/scripts/hooks/json-helper.cjs

@@ -45,9 +45,16 @@
 //                                          once; prints none | busy | busy claim |
 //                                          skipped tracked | skipped unknown | moved <mode>
 //                                          and its backup, cause and notes
+//   tracked-area <curation|memory|both> <root>
+//                                          Does git track files in the data folders of the area
+//                                          at the root? Prints tracked | untracked | unknown, and
+//                                          for unknown a second line `cause <word>`
 //
-// Every curation op above except claim-queue, release-claim and move-ledger first
-// refreshes the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
+// Every curation op above except claim-queue, release-claim, move-ledger and tracked-area
+// first refreshes the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
+// Where git tracks files in the curation data folders, or does not say whether it does,
+// every curation op refuses with kind `tracked`, exit 1 and an empty stdout, and changes
+// nothing; the answer is asked once per process.
 
 'use strict';
 
@@ -88,6 +95,21 @@ function curationMove() {
   return curationMoveModule;
 }
 
+/** The tracked-areas check, once loaded; see trackedAreas(). */
+let trackedAreasModule = null;
+
+/**
+ * The tracked-areas check, loaded on first use and memoized. Only the tracked-area op
+ * loads it from here: a leaf that requires node built-ins and the path helpers, never
+ * the store.
+ *
+ * @returns {object}
+ */
+function trackedAreas() {
+  if (trackedAreasModule === null) trackedAreasModule = require('./lib/tracked-areas.cjs');
+  return trackedAreasModule;
+}
+
 /** The bytes each read of stdin asks for. */
 const STDIN_READ_BYTES = 64 * 1024;
 
@@ -624,6 +646,26 @@ try {
       break;
     }
 
+    // -------------------------------------------------------------------------
+    // tracked-area <curation|memory|both> <root>
+    // Does git track files in the data folders of the area at the root
+    // (inspectTrackedAreaOnce, tracked-areas.cjs)? Not a curation op: it sends no
+    // heartbeat and loads only the check. The root is an argument, so the shell gate
+    // names the root it decided on; it stays one argv word, never a shell word. The
+    // answer is asked once per root and area for the life of the process.
+    // stdout: tracked | untracked | unknown, and for unknown a second line
+    // `cause <word>` (one fixed word that says why git did not answer)
+    // -------------------------------------------------------------------------
+    case 'tracked-area': {
+      const { AREA_PATHSPECS, inspectTrackedAreaOnce } = trackedAreas();
+      if (args.length !== 2 || !Object.prototype.hasOwnProperty.call(AREA_PATHSPECS, args[0])) {
+        exitWithUsage('tracked-area <curation|memory|both> <root> (the root is an absolute path)');
+      }
+      const { answer, cause } = inspectTrackedAreaOnce(args[1], args[0]);
+      process.stdout.write(answer === 'unknown' ? `unknown\ncause ${cause}\n` : `${answer}\n`);
+      break;
+    }
+
     default:
       process.stderr.write(`json-helper: unknown operation "${op}"\n`);
       process.exit(1);

package/src/assets/scripts/hooks/lib/curation-store.cjs

@@ -10,7 +10,8 @@
 // means a broken invariant or an I/O failure, never an expected outcome; a lock
 // held by withDecisionsLock is released on every path, the throw included.
 //
-// Loading: node built-ins and three sibling libs only. This module never requires
+// Loading: node built-ins and four sibling libs only (the path helpers, the lock, the
+// path guard and the tracked-areas check). This module never requires
 // decisions-format.cjs or render-decisions.cjs at load time: both require it, for
 // the status list and the one-line and inactive-note text they share with `list`.
 //
@@ -58,6 +59,7 @@ const {
 } = require('./project-paths.cjs');
 const { acquireMkdirLock, releaseLock } = require('./mkdir-lock.cjs');
 const { safePath } = require('./safe-path.cjs');
+const { inspectTrackedAreaOnce } = require('./tracked-areas.cjs');
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -628,6 +630,36 @@ function linkedFolder(opName, dir) {
   };
 }
 
+/**
+ * The refusal of an op run where git tracks files in the curation data folders under
+ * `root` (the curation folder, the old ledger folder and the backup folders), or does
+ * not say whether it does, or null where git tracks none. A folder that git tracks is the
+ * repository's content, so the curation feature is paused there: the op reads and writes
+ * nothing. The messages state the fact and name no command; the root is shown so the
+ * folder can be found. The check asks git about the index, not the disk, so it holds
+ * whether or not the folder is on disk, and it makes no git call for a root with no `.git`
+ * entry. It comes first in every op, before a ledger file is read, a lock is taken or a git
+ * call of the op's own is made. The answer is asked once per root for the life of the
+ * process (inspectTrackedAreaOnce), so the heartbeat, the op and its lock share one call.
+ *
+ * The refusal carries `reason`, `tracked` where git tracks files and `unknown` where it
+ * did not answer, so a caller that picks a notice reads the field, never the message.
+ *
+ * @param {string} opName - operation name, for the message
+ * @param {string} root - project root
+ * @returns {{ ok: false, error: { kind: 'tracked', reason: 'tracked'|'unknown', message: string } } | null}
+ */
+function trackedCurationArea(opName, root) {
+  const { answer } = inspectTrackedAreaOnce(root, 'curation');
+  if (answer === 'untracked') return null;
+  const reason = answer === 'tracked' ? 'tracked' : 'unknown';
+  const fact = reason === 'tracked' ? 'git tracks files' : 'git did not answer whether it tracks files';
+  return {
+    ok: false,
+    error: { kind: 'tracked', reason, message: `${opName}: ${fact} in the curation data folders under ${root}; nothing was written` },
+  };
+}
+
 /** The Stats of `file` without following a link, or null when nothing is there. */
 function lstatOrNull(file) {
   try {
@@ -744,16 +776,23 @@ function isResult(value) {
  * names. Refused here, before the lock is taken, so every writer refuses in one
  * place; the claim heartbeat makes the same check, and read-only paths still read.
  *
+ * A writer also refuses with `tracked`, changing nothing, where git tracks files in the
+ * curation data folders under its root, or does not say whether it does
+ * (trackedCurationArea). That check follows the link check and comes before the journal,
+ * the folder check and the lock, so a paused project gets no lock folder.
+ *
  * @param {string} opName - operation name, for messages
  * @param {string} root - project root
  * @param {() => { ok: boolean }} fn - the locked body; it must return a Result
  * @param {{ timeoutMs?: number, staleMs?: number }} [opts]
  * @returns {{ ok: true, value?: unknown } | { ok: false, error: { kind: string, message: string } }}
- *   fn's Result, or an error of kind `not-a-directory`, `no-curation-dir` or `busy`.
+ *   fn's Result, or an error of kind `not-a-directory`, `tracked`, `no-curation-dir` or `busy`.
  */
 function withDecisionsLock(opName, root, fn, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_MS, staleMs = LOCK_STALE_MS } = {}) {
   const linked = linkedCurationFolder(root);
   if (linked !== null) return linkedFolder(opName, linked);
+  const paused = trackedCurationArea(opName, root);
+  if (paused !== null) return paused;
   const journal = moveJournalPathOrNull(root);
   const oldFolder = path.join(root, '.devflow', LEGACY_NAMES.folder);
   if (journal !== null && moveJournalHoldsWriters(journal, oldFolder)) return unfinishedMove(opName, journal);
@@ -1344,7 +1383,7 @@ function lastActivityMs(row) {
  * @param {{ now?: number, timeoutMs?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { rotated: number, appended: number } } | { ok: false, error: { kind: string, message: string } }}
  *   rotated: rows removed from the log; appended: rows added to the archive.
- *   Errors are withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   Errors are withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
 function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
   return withDecisionsLock('rotate-observations', root, () => {
@@ -1407,7 +1446,7 @@ function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
  * @param {{ now?: number, timeoutMs?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { cleared: number, kept: number } } | { ok: false, error: { kind: string, message: string } }}
  *   cleared: rows removed from the log; kept: rows left in it. Error kinds:
- *   ledger-malformed, and withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   ledger-malformed, and withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
 function clearUnreferenced(root, { now = Date.now(), timeoutMs } = {}) {
   return withDecisionsLock('clear', root, () => {
@@ -1475,7 +1514,7 @@ function removeEmptyDir(dir) {
  * @param {{ timeoutMs?: number }} [opts]
  * @returns {{ ok: true, value: { removed: number } } | { ok: false, error: { kind: string, message: string } }}
  *   removed: the entries removed from the curation directory. Errors are
- *   withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
 function resetCuration(root, { timeoutMs } = {}) {
   const curationDir = getCurationDir(root);
@@ -1643,7 +1682,8 @@ function moveQueueToClaim(queuePath, claimPath) {
  * clobber a batch, mv kept the queue's old mtime so a fresh claim could look stale
  * at once, and an unconditional final unlink deleted another run's claim.
  *
- * Without .devflow/curation/ it answers none and creates nothing.
+ * Without .devflow/curation/ it answers none and creates nothing; where git tracks files
+ * in the curation data folders it refuses, kind `tracked`, before it looks (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ now?: number, token?: string, timeoutMs?: number }} [opts]
@@ -1654,6 +1694,8 @@ function moveQueueToClaim(queuePath, claimPath) {
  */
 function claimQueue(root, { now = Date.now(), token = newClaimToken(), timeoutMs } = {}) {
   assertClaimToken('claimQueue', token);
+  const paused = trackedCurationArea('claim-queue', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return { ok: true, value: { state: 'none' } };
   return withDecisionsLock('claim-queue', root, () => {
     const claimPath = getCurationPendingTurnsProcessingPath(root);
@@ -1693,7 +1735,7 @@ function claimQueue(root, { now = Date.now(), token = newClaimToken(), timeoutMs
  * @param {string} token
  * @param {{ timeoutMs?: number }} [opts]
  * @returns {{ ok: true, value: { state: 'released'|'not-owner'|'gone' } } | { ok: false, error: { kind: string, message: string } }}
- *   errors include withDecisionsLock's not-a-directory, no-curation-dir and busy
+ *   errors include withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy
  * @throws {TypeError} when `token` is not a claim token
  */
 function releaseClaim(root, token, { timeoutMs } = {}) {
@@ -1722,14 +1764,17 @@ function releaseClaim(root, token, { timeoutMs } = {}) {
  * takes no lock — json-helper sends it before each curation op runs. A claim in a
  * curation tree reached through a symbolic link is left alone (D-NO-LINKED-TREE):
  * `lutimes` follows a linked folder above the claim, and the op that follows
- * refuses that tree anyway.
+ * refuses that tree anyway. A claim in a project whose curation data folders git
+ * tracks, or where git does not answer, is left alone as well (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ now?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { touched: boolean } } | { ok: false, error: { kind: 'heartbeat-failed', message: string } }}
  */
 function touchClaim(root, { now = Date.now() } = {}) {
-  if (linkedCurationFolder(root) !== null) return { ok: true, value: { touched: false } };
+  if (linkedCurationFolder(root) !== null || trackedCurationArea('heartbeat', root) !== null) {
+    return { ok: true, value: { touched: false } };
+  }
   const claimPath = getCurationPendingTurnsProcessingPath(root);
   const at = new Date(now);
   try {
@@ -2231,13 +2276,15 @@ function restoreFirst(id, carriers) {
  *   observations: the count the log row holds afterwards; reprojected: the
  *   anchors re-projected, in anchor order. Error kinds: invalid-input (with
  *   problems), duplicate-log-id, restore-first, cannot-reproject, and
- *   withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} when `mode` is not a put mode
  */
 function putObservation(root, mode, input, { now = Date.now(), timeoutMs, scopeMatches } = {}) {
   if (!VALIDATION_MODES.includes(mode)) {
     throw new TypeError(`putObservation: mode must be one of ${VALIDATION_MODES.join(', ')}, got '${mode}'`);
   }
+  const paused = trackedCurationArea('put-observation', root);
+  if (paused !== null) return paused;
   const matches = scopeMatches || gitScopeMatcher(root);
   return withDecisionsLock('put-observation', root, () => putUnderLock(root, mode, input, { now, scopeMatches: matches }), { timeoutMs });
 }
@@ -2303,14 +2350,17 @@ function putUnderLock(root, mode, input, { now, scopeMatches }) {
  * The data behind `list`, read-only: buildListing over the ledger and the log as
  * they are, every glob scope checked against the files git tracks. Malformed
  * lines are counted, never quarantined (D-QUARANTINE-MALFORMED). Refuses without
- * .devflow/curation/ (D-NO-STRAY-TREE).
+ * .devflow/curation/ (D-NO-STRAY-TREE), and, before it reads a file, where git tracks files
+ * in the curation data folders (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ scopeMatches?: (glob: string) => boolean }} [opts] - default gitScopeMatcher(root)
  * @returns {{ ok: true, value: { active: object[], inactive: object[], observations: object[], integrity: object[], malformed: { ledger: number, log: number } } }
- *   | { ok: false, error: { kind: 'no-curation-dir', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-curation-dir', message: string } }}
  */
 function readListing(root, { scopeMatches } = {}) {
+  const paused = trackedCurationArea('list', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return noCurationDir('list', root);
   const { ledgerRows, logRows, rejected } = readCurationState(root);
   return {
@@ -2393,14 +2443,17 @@ function formatListing(listing) {
  * the log and the history as they are. When lines were skipped as malformed
  * (D-QUARANTINE-MALFORMED), a found entry gains `malformed: { ledger, log }` and
  * a not-found message says a skipped line may hold it. Refuses without
- * .devflow/curation/ (D-NO-STRAY-TREE).
+ * .devflow/curation/ (D-NO-STRAY-TREE), and, before it reads a file, where git tracks files
+ * in the curation data folders (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {string} key - an anchor id or an observation id
  * @returns {{ ok: true, value: { key: string, ledger: object[], log: object|null, history_versions: object[], flags: object[], malformed?: { ledger: number, log: number } } }
- *   | { ok: false, error: { kind: 'no-curation-dir'|'invalid-key'|'not-found', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-curation-dir'|'invalid-key'|'not-found', message: string } }}
  */
 function showByKey(root, key) {
+  const paused = trackedCurationArea('show', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return noCurationDir('show', root);
   const { ledgerRows, logRows, rejected } = readCurationState(root);
   const shown = showEntry(key, ledgerRows, logRows, { historyVersions: id => historyVersions(root, id) });
@@ -2448,10 +2501,12 @@ function warmScopeMatcher(ledgerRows, scopeMatches) {
  *   now: epoch ms (default Date.now()); scopeMatches: default gitScopeMatcher(root)
  * @returns {{ ok: true, value: { ref: { ref: 'origin/HEAD'|'HEAD', commit: string } | null, due: Array<{ anchor_id: string, reason: string, bytes: number }> } }
  *   | { ok: false, error: { kind: string, message: string } }}
- *   due is selectDue's answer; errors are withDecisionsLock's not-a-directory,
+ *   due is selectDue's answer; errors are withDecisionsLock's tracked, not-a-directory,
  *   no-curation-dir and busy
  */
 function claimDue(root, { now = Date.now(), timeoutMs, scopeMatches } = {}) {
+  const paused = trackedCurationArea('claim-due', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return noCurationDir('claim-due', root);
   const matches = scopeMatches || gitScopeMatcher(root);
   const ref = resolveVerifyRef(root);
@@ -2725,12 +2780,14 @@ function mintAnchor(ledgerRows, type, citedAnchors) {
  *   | { ok: false, error: { kind: string, message: string } }}
  *   Error kinds: not-in-log, duplicate-log-id, already-promoted, v1-observation,
  *   type-mismatch, cited-numbers-exhausted, and withDecisionsLock's
- *   not-a-directory, no-curation-dir and busy.
+ *   tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a type other than decision or pitfall, or a malformed obsId
  */
 function assignAnchor(root, type, obsId, { now = Date.now(), timeoutMs, citedAnchors } = {}) {
   if (anchorPrefixFor(type) === null) throw new TypeError(`assignAnchor: type must be 'decision' or 'pitfall', got '${type}'`);
   if (typeof obsId !== 'string' || !OBS_ID_RE.test(obsId)) throw new TypeError('assignAnchor: obsId must be an observation id');
+  const paused = trackedCurationArea('assign-anchor', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return noCurationDir('assign-anchor', root);
   const cited = citedAnchors || collectCitedAnchorIds(root);
   return withDecisionsLock('assign-anchor', root, () => assignUnderLock(root, type, obsId, { now, cited }), { timeoutMs });
@@ -2884,7 +2941,7 @@ function recordRefreshHistory(root, plans, ledgerRows, { now }) {
  * @returns {{ ok: true, value: { refreshed: Array<{ anchor_id: string, state: 'verified'|'reprojected'|'unchanged' }> } }
  *   | { ok: false, error: { kind: string, message: string, problems?: Array<{ anchor_id: string, message: string }> } }}
  *   refreshed: each anchor once, in the order given. Error kinds: refused (with
- *   problems), and withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   problems), and withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} when anchorIds is empty or holds anything but anchor ids
  */
 function refreshAnchors(root, anchorIds, { verified = false, now = Date.now(), timeoutMs } = {}) {
@@ -3067,9 +3124,11 @@ function restoreRefusal(kind, message) {
  * @param {{ verifyRef?: { ref: 'origin/HEAD'|'HEAD', commit: string } | null }} [opts]
  *   verifyRef: default resolveVerifyRef(root); null when there is no commit to check
  * @returns {{ ok: true, value: { path: string, quote: string, ref: string, commit: string } }
- *   | { ok: false, error: { kind: 'no-verify-ref'|'not-at-ref'|'git-failed'|'quote-not-found', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-verify-ref'|'not-at-ref'|'git-failed'|'quote-not-found', message: string } }}
  */
 function quoteAtRef(root, at, quote, { verifyRef } = {}) {
+  const paused = trackedCurationArea('retire-anchor', root);
+  if (paused !== null) return paused;
   const checkedAt = verifyRef === undefined ? resolveVerifyRef(root) : verifyRef;
   if (checkedAt === null) {
     return retireRefusal('no-verify-ref', 'there is no commit to check the quote at (not a git repository, or no commit yet); nothing was written');
@@ -3121,7 +3180,7 @@ function quoteAtRef(root, at, quote, { verifyRef } = {}) {
  *   kinds: invalid-input (with problems), quoteAtRef's, not-found,
  *   duplicate-anchor, already-inactive, successor-not-found,
  *   successor-duplicate-anchor, successor-inactive, and withDecisionsLock's
- *   not-a-directory, no-curation-dir and busy.
+ *   tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a malformed anchorId or a status that is not inactive
  */
 function retireAnchor(root, anchorId, status, input, { now = Date.now(), timeoutMs, verifyRef } = {}) {
@@ -3129,6 +3188,8 @@ function retireAnchor(root, anchorId, status, input, { now = Date.now(), timeout
   if (!INACTIVE_STATUSES.includes(status)) {
     throw new TypeError(`retireAnchor: status must be one of ${INACTIVE_STATUSES.join(', ')}, got '${status}'`);
   }
+  const paused = trackedCurationArea('retire-anchor', root);
+  if (paused !== null) return paused;
   if (!hasCurationDir(root)) return noCurationDir('retire-anchor', root);
   const problems = retireInputProblems(anchorId, status, input);
   if (problems.length > 0) return invalidInput('retire-anchor', problems);
@@ -3200,7 +3261,7 @@ function retireUnderLock(root, anchorId, status, note, { now }) {
  * @returns {{ ok: true, value: { anchor_id: string, status: 'Accepted'|'Active' } }
  *   | { ok: false, error: { kind: string, message: string } }}
  *   Error kinds: not-found, duplicate-anchor, already-active, type-mismatch, and
- *   withDecisionsLock's not-a-directory, no-curation-dir and busy.
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a malformed anchorId
  */
 function restoreAnchor(root, anchorId, { now = Date.now(), timeoutMs } = {}) {
@@ -3268,6 +3329,7 @@ module.exports = {
   writeJsonlAtomic,
   // Locking
   hasCurationDir,
+  trackedCurationArea,
   withDecisionsLock,
   // State and the ledger registry
   readCurationState,

package/src/assets/scripts/hooks/lib/render-decisions.cjs

@@ -51,6 +51,7 @@ const {
   isV2,
   readJsonl,
   hasCurationDir,
+  trackedCurationArea,
   withDecisionsLock,
   writeFileAtomic,
 } = require('./curation-store.cjs');
@@ -397,12 +398,19 @@ function renderCommand(root) {
  * `--check`: render in memory and compare with the files on disk, naming each
  * file that differs or is missing; exit 1 on any drift. It writes nothing and
  * takes no lock — taking it would create the lock directory — and refuses
- * without the curation directory (D-NO-STRAY-TREE).
+ * without the curation directory (D-NO-STRAY-TREE). Where git tracks files in the
+ * curation data folders, or does not say whether it does, it refuses first, exit 1:
+ * it reads no file there (trackedCurationArea).
  *
  * @param {string} root
  * @returns {number} exit code
  */
 function checkCommand(root) {
+  const paused = trackedCurationArea(CLI_NAME, root);
+  if (paused !== null) {
+    process.stderr.write(`${paused.error.message}\n`);
+    return 1;
+  }
   if (!hasCurationDir(root)) {
     process.stderr.write(`${CLI_NAME}: no .devflow/curation/ under ${root} — run from the project root\n`);
     return 1;