devflow-kit 3.1.0 → 3.2.0

package/src/assets/commands/implement.mds

@@ -25,7 +25,13 @@ Orchestrate a single task through implementation by spawning specialized agents.
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/implement`:
+What follows `/implement` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Plan document path: `.devflow/docs/design/42-jwt-auth.2026-04-07_1430.md` (path to an existing `.md` file)
 - Issue reference: `#42`
 - Task description: "implement JWT auth"
@@ -53,15 +59,13 @@ If the user prompt does NOT match re-validation, proceed with the full pipeline
 
 **Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION_GUIDANCE, ISSUE_NUMBER, EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL, PR_EXCEPTIONS, TEST_PLAN, EVIDENCE_FILE, PR_TEST_PLAN_BLOCK, REVIEW_PUBLICATION
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:dependency-research`. If a skill fails to load, continue without it.
-
 Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
 {{docs_root()}}
 
 {{evidence_policy()}}
 
-**Plan Document Handling** (when $ARGUMENTS is a path ending in `.md`):
+**Plan Document Handling** (when `COMMAND_INPUT` is a path ending in `.md`):
 1. Read the plan document from the path provided
 2. Extract from YAML frontmatter: `execution-strategy`, `context-risk`, `issue` number
 3. Extract from body: Subtask Breakdown, Implementation Plan, Patterns to Follow, Acceptance Criteria
@@ -72,23 +76,25 @@ Record the current branch name as `BASE_BRANCH` - this will be the PR target.
 
 If `PR_DESCRIPTION_GUIDANCE` was not set above (non-plan paths: issue input or task description), set it to `(none)`.
 
+**Empty input.** When `COMMAND_INPUT` is empty — a plan handoff arrives this way, with the plan already in the conversation — there is no argument to name the branch from, and the Git agent sees none of this conversation. Write the description yourself: one line, taken from the plan's title or, with no plan, from the conversation. Send it as the setup-task `TASK_DESCRIPTION` below.
+
 Spawn Git agent to set up task environment. The Git agent derives the branch name automatically from the issue or task description:
 
 ```
 Agent(subagent_type="Git"):
 "OPERATION: setup-task
 BASE_BRANCH: {current branch name}
-ISSUE_INPUT: {$ARGUMENTS verbatim, when it is a single whitespace-delimited token that does not end in .md; when it ends in .md, the plan frontmatter's issue value verbatim unless absent or pending — otherwise omit}
-TASK_DESCRIPTION: {$ARGUMENTS verbatim, when it is two or more whitespace-delimited tokens — otherwise omit}
+ISSUE_INPUT: {COMMAND_INPUT verbatim, when it is a single whitespace-delimited token that does not end in .md; when it ends in .md, the plan frontmatter's issue value verbatim unless absent or pending — otherwise omit}
+TASK_DESCRIPTION: {COMMAND_INPUT verbatim, when it is two or more whitespace-delimited tokens; when COMMAND_INPUT is empty, the one-line description you wrote above — otherwise omit}
 ISSUE_REQUIRED: {ISSUE_REQUIRED}
 APPLY_CONVENTIONS: {APPLY_CONVENTIONS}
-PLAN_ARTIFACT_PATH: {path to plan document if $ARGUMENTS ends in .md, otherwise (none)}
+PLAN_ARTIFACT_PATH: {path to plan document if COMMAND_INPUT ends in .md, otherwise (none)}
 Derive branch name from issue or description, create feature branch, and fetch issue if specified.
 Return the branch setup summary."
 ```
 
 The issue token is forwarded **unclassified**, and the routing is decided by
-SHAPE alone — how many tokens `$ARGUMENTS` has, and whether it ends in `.md`.
+SHAPE alone — how many tokens `COMMAND_INPUT` has, and whether it ends in `.md`.
 
 `setup-task` is the one step that has resolved a provider, and therefore the only
 one that knows what an issue reference looks like on this machine: `#123`,
@@ -133,7 +139,7 @@ visible, a silently discarded request is not.
 
 **Test plan.** Before any Code spawn, give the task a test plan in the evidence file `{worktree}/.devflow/docs/evidence-{branch_slug}.md` (`EVIDENCE_FILE`) — unlike the handoff file, it stays after the PR exists. It holds up to three sections, in this order and nothing else: `## Test Plan`; `## Evidence Exceptions`, a byte copy of `PR_EXCEPTIONS` present only while that is not `(none)`; and `## Claims`, always last, so every claim is appended at the end of the file. Create the file if absent; if it exists, replace its `## Test Plan` and `## Evidence Exceptions` sections and keep `## Claims` byte-identical.
 
-Write the `## Test Plan` section: when `$ARGUMENTS` is a plan document with a `## Test Plan` section, copy that section's lines verbatim; otherwise write one TP line per acceptance criterion the plan, the issue or the task text states, numbered from `TP-1`. Never invent a criterion, and word every scenario yourself in plain words: the lines reach the PR body, so a scenario holds no `#`, `@` or `/` — no issue reference, mention, closing keyword target or URL — and the files a TP covers go in its `files:` field. Each line follows the TP-line contract:
+Write the `## Test Plan` section: when `COMMAND_INPUT` is a plan document with a `## Test Plan` section, copy that section's lines verbatim; otherwise write one TP line per acceptance criterion the plan, the issue or the task text states, numbered from `TP-1`. Never invent a criterion, and word every scenario yourself in plain words: the lines reach the PR body, so a scenario holds no `#`, `@` or `/` — no issue reference, mention, closing keyword target or URL — and the files a TP covers go in its `files:` field. Each line follows the TP-line contract:
 
 {{test_plan_line()}}
 
@@ -314,7 +320,7 @@ ISSUE_PR_LINK: {ISSUE_PR_LINK captured in Phase 1, or (none)}"
 After Code agent completes, spawn Validate agent to verify correctness:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {list of files from Code agent output}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."
@@ -394,7 +400,7 @@ If Scrutinize agent returns BLOCKED, report to user and halt.
 If Scrutinize agent made code changes (status: FIXED), spawn Validate agent to verify:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {files modified by Scrutinize agent}
 VALIDATION_SCOPE: changed-only
 Verify Scrutinize agent's fixes didn't break anything."
@@ -442,7 +448,7 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
-   Agent(subagent_type="Validate", model="haiku"):
+   Agent(subagent_type="Validate"):
    "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```
@@ -490,7 +496,7 @@ After every Test agent run — PASS or FAIL, first run or retry — append its T
    ```
    - Spawn Validate agent to verify fix didn't break tests:
    ```
-   Agent(subagent_type="Validate", model="haiku"):
+   Agent(subagent_type="Validate"):
    "FILES_CHANGED: {files modified by fix Code agent}
    VALIDATION_SCOPE: changed-only"
    ```

package/src/assets/commands/plan.mds

@@ -26,7 +26,13 @@ The orchestrator only spawns agents and gates — all analytical work is done by
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/plan`:
+What follows `/plan` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Opens with a candidate issue reference → issue mode (one candidate = single-ref, more than one = multi-issue)
 - Path to existing `.md` file → **error**: "Use /implement with plan documents"
 - Other text → feature description
@@ -66,7 +72,7 @@ Explore the user's intent through focused Socratic questioning before spawning a
 
 **Step 0 — Fetch issue(s)** (issue mode only; skip for feature-description and empty modes):
 
-- **Single-ref** (one candidate ref in `$ARGUMENTS`):
+- **Single-ref** (one candidate ref in `COMMAND_INPUT`):
 
   ```
   Agent(subagent_type="Git"):
@@ -106,8 +112,6 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 **Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 **Requires:** CONFIRMED_SCOPE
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:software-design`, `devflow:security`, `devflow:design-review`. If a skill fails to load, continue without it.
-
 Spawn Skim agent for codebase context:
 
 ```
@@ -136,7 +140,7 @@ Pass `FEATURE_KNOWLEDGE` alongside `DECISIONS_CONTEXT` to Explore and Design age
 **Produces:** EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, DECISIONS_CONTEXT
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated."
+Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -265,7 +269,7 @@ User can:
 **Produces:** IMPL_EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope:
+Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -294,7 +298,7 @@ Combine into: patterns to follow, integration points, reusable code, edge cases"
 **Produces:** PLAN_OUTPUTS
 **Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS, DECISIONS_CONTEXT
 
-Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis:
+Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
 
 | Focus | Output |
 |-------|--------|
@@ -470,7 +474,7 @@ Spawn a Git agent with `OPERATION: ensure-traceable-issue`:
 ```
 Agent(subagent_type="Git"):
 "OPERATION: ensure-traceable-issue
-ISSUE_INPUT: {the raw candidate token from $ARGUMENTS if /plan was invoked with an issue reference, else omit}
+ISSUE_INPUT: {the raw candidate token from COMMAND_INPUT if /plan was invoked with an issue reference, else omit}
 TASK_DESCRIPTION: {Gate 0 confirmed scope — one-line title}
 INITIAL_REQUEST: {the Gate 0 confirmed scope statement}
 REQUIREMENTS: {discovered requirements summary from Phase 6 gap synthesis}

package/src/assets/commands/release.md

@@ -17,13 +17,19 @@ Release the project using adaptive learned configuration. On first run, scans th
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/release`:
+What follows `/release` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Explicit version: `v1.2.3` or `1.2.3`
 - Bump type: `patch`, `minor`, `major`
 - Flag: `--dry-run`
 - Empty: interactive mode (will ask for version)
 
-Parse from $ARGUMENTS:
+Parse from `COMMAND_INPUT`:
 - `VERSION`: explicit version string if present (strip leading `v`)
 - `BUMP_TYPE`: `patch | minor | major` if bump type provided
 - `DRY_RUN`: true if `--dry-run` present, false otherwise

package/src/assets/commands/research.mds

@@ -20,7 +20,13 @@ Research a topic by spawning parallel Research agents across multiple research t
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/research`:
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Research question: "best caching strategies"
 - Comparison question: "compare React vs Svelte for our use case"
 - Empty: use conversation context
@@ -111,7 +117,7 @@ If external research was skipped due to tool unavailability: inform user.
 1. If `codebase` type was not in RESEARCH_PLAN → skip
 2. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
 3. Use AskUserQuestion: "No feature knowledge exists for {researched area}. Create one?"
-4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to load `devflow:feature-knowledge`, write `KNOWLEDGE.md`, and update `index.md` directly
+4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to write `KNOWLEDGE.md` and update `index.md` directly
 5. Set FEATURE_KNOWLEDGE_STATUS = created or skipped
 
 **Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.

package/src/assets/commands/resolve.mds

@@ -275,7 +275,7 @@ If no fixes were made (CODE_AGENT_RESULTS contains 0 commits) → set VERIFICATI
 Otherwise, spawn Validate agent:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {list of files from Code agent output}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."

package/src/assets/mds/tracker/_github.mds

@@ -226,13 +226,13 @@ This issue reached the size limit.
 
 Load when the resolved tracker provider is `github` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` provided: append a `## Closed Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
+   - If `SHIPPED_ISSUES` provided: append a `## Shipped Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
 @end
 
 @define gather_release_evidence():

package/src/assets/mds/tracker/_jira.mds

@@ -180,13 +180,13 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - {{common.ref_preflight_list("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`", "", "", " and the section is omitted rather than rendered empty.")}}
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the key itself on its own line, and record the discard under `### Substitutions`.
 

package/src/assets/mds/tracker/_linear.mds

@@ -218,13 +218,13 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `linear` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - {{common.ref_preflight_list("linear", "**either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`", "**ASCII-upper-normalise every entry first.** ", ", never joined into one alternation", " and the section is omitted rather than rendered empty.")}}
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the reference itself on its own line, and record the discard under `### Substitutions`.
 

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

@@ -1,7 +1,7 @@
 --- 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.
+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.
 
 Routing (Agent tool) — pick the roster agent that fits the work:
 - Search and listing: Explore. Codebase orientation: Skim.
@@ -14,7 +14,8 @@ Stays mainline (judgment work): conversation, decisions, routing, synthesizing a
 Operating rules:
 - 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 the substance in the prompt — not a pointer to it.
+- 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 matching KNOWLEDGE.md content as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
 - Decisions (direct delegations only — workflow skills load their own): pass the index named under PROJECT DECISIONS as DECISIONS_CONTEXT — its content, read once — to every agent that takes it.
-- 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 the full plan. Do not pause to ask.
+- 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

@@ -2,7 +2,7 @@
 
 # background-memory-update — Eager working-memory refresh worker
 # Spawned as a detached background process by memory-worker (Stop hook) after the
-# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` (sonnet 4.6) →
+# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` (sonnet 5.5) →
 # rewrites WORKING-MEMORY.md with a git-reconciliation stamp on line 1.
 #
 # Applies the LLM-vs-plumbing principle: artifact content (WORKING-MEMORY.md) is
@@ -106,6 +106,18 @@ if ! command -v cksum >/dev/null 2>&1; then
   exit 0
 fi
 
+# --- Never write through a symbolic link (D-HOOKS-NO-SYMLINK, git-marker) ---
+# The lock (`mkdir`), the batch merge (`>>`), the claim heartbeat and the success
+# stamp (`touch`) write these paths in place; the claim and the trim rename onto the
+# batch and the swap onto the working memory, and `mv` moves a file into the folder
+# a link at its target names. The trim's copy is created only where nothing stands.
+# So the run is skipped, before it takes the lock or starts an LLM run, when any of
+# these paths or a folder above them is a link.
+if ! df_no_symlink_below "$PROJECT_ROOT" "$LOCK_DIR" "$QUEUE_FILE" "$PROCESSING_FILE" "$OK_FILE" "$MEMORY_FILE"; then
+  log "SKIP: a symbolic link sits on the path to the memory files in $MEMORY_DIR; nothing written"
+  exit 0
+fi
+
 # --- Worker-level lock (300s stale-break — much longer than learning-lock's 30s) ---
 # This prevents a second worker (spawned 121s later) from double-writing WORKING-MEMORY.md
 # while the first worker's claude -p call (up to 120s) is still in flight.
@@ -210,8 +222,20 @@ if [ -f "$PROCESSING_FILE" ]; then
   _PROC_LINES=$(wc -l < "$PROCESSING_FILE" | tr -d ' ')
   if [ "$_PROC_LINES" -gt "$PROC_OVERFLOW_CAP" ]; then
     _PROC_TMP="$PROCESSING_FILE.tmp.$$"
-    tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP" && mv "$_PROC_TMP" "$PROCESSING_FILE" || rm -f "$_PROC_TMP" 2>/dev/null || true
-    log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    # SEC-2: the batch is the claimed queue, 0600 like the queue itself, and the
+    # cold path at session start moves it back to the queue. mv gives it the
+    # trimmed copy's inode and mode, so the copy is created under umask 077, and
+    # only where nothing stands at its name: builtin tests come first, so an entry
+    # already there, a link to a FIFO or a device included, is never opened
+    # (noclobber alone would open one, as no regular file stands there), and
+    # noclobber then makes the create itself exclusive. Such an entry is removed
+    # instead, and the batch is left untrimmed.
+    if [ ! -e "$_PROC_TMP" ] && [ ! -L "$_PROC_TMP" ] && (umask 077 && set -o noclobber && tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP") && mv "$_PROC_TMP" "$PROCESSING_FILE"; then
+      log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    else
+      rm -f "$_PROC_TMP" 2>/dev/null || true
+      log "Processing overflow: not truncated, its copy could not be written ($_PROC_LINES lines)"
+    fi
   fi
 elif [ -f "$QUEUE_FILE" ]; then
   mv "$QUEUE_FILE" "$PROCESSING_FILE" 2>/dev/null || { log "SKIP: failed to claim queue (race condition — another worker got it)"; exit 0; }
@@ -340,15 +364,22 @@ log "Built $TURN_COUNT turns from queue"
 # on either side, the CAS must treat it as CONFLICT rather than a match — separating
 # the "cksum invocation failure" sentinel from "file absent" keeps the "resolves toward
 # false-conflict, never false-success" invariant true even when cksum errors.
+#
+# D-HOOKS-NO-SYMLINK (git-marker): the existing memory goes into the prompt, so a
+# working memory a symbolic link leads to is treated as absent. A link at its own
+# path has already skipped the run, since the swap renames onto it (above), so
+# only one that appeared since can reach this read.
+MEMORY_PRESENT=""
+if df_file_below "$PROJECT_ROOT" "$MEMORY_FILE"; then MEMORY_PRESENT="yes"; fi
 CKSUM_FAILED="false"
 PRE_RUN_CKSUM="ABSENT"
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   PRE_RUN_CKSUM=$(cksum "$MEMORY_FILE" 2>/dev/null) || CKSUM_FAILED="true"
 fi
 
 EXISTING_MEMORY=""
 MEMORY_READ_LIMIT=65536  # bytes — keep prompt under context limit
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   EXISTING_MEMORY=$(head -c "$MEMORY_READ_LIMIT" "$MEMORY_FILE")
 fi
 
@@ -469,7 +500,7 @@ Instructions:
 EOF
 )
 
-log "Spawning claude -p (model claude-sonnet-4-6, ${TURN_COUNT} turns)"
+log "Spawning claude -p (model claude-sonnet-5-5, ${TURN_COUNT} turns)"
 # SECURITY: never log PROMPT — it contains turn content which may include secrets
 
 # --- Watchdog timeout (overridable for tests: DEVFLOW_BG_WATCHDOG_SECS=2) ---
@@ -508,7 +539,7 @@ fi
 # Job-control notifications go to stderr which is redirected to the log — suppress them.
 set -m
 DEVFLOW_BG_UPDATER=1 "$CLAUDE_BIN" -p \
-  --model claude-sonnet-4-6 \
+  --model claude-sonnet-5-5 \
   --dangerously-skip-permissions \
   --allowedTools 'Read,Write' \
   --output-format text \
@@ -572,13 +603,28 @@ fi
 # Each state is assigned exactly once at the point it is decided (single OUTCOME
 # variable, three states).
 verify_and_swap() {
-  [ -f "$STAGED_FILE" ] && [ -s "$STAGED_FILE" ] || {
+  # A symbolic link at the staged path counts as no staged file (D-HOOKS-NO-SYMLINK,
+  # git-marker): `head` below would read the file it names, and the swap's `mv`
+  # would rename the link itself into the working memory's place. The worker
+  # removed that path before the LLM run, so a link there was planted during it.
+  # df_file_below checks it before both, and logs the refusal once.
+  df_file_below "$PROJECT_ROOT" "$STAGED_FILE" && [ -s "$STAGED_FILE" ] || {
     log "WARN: staged file missing or empty after claude -p run"; OUTCOME="failed"; return; }
   case "$(head -1 "$STAGED_FILE" 2>/dev/null || echo "")" in
     "<!-- memory-head:"*) : ;;
     *) log "WARN: staged file exists but stamp missing on line 1 — treating as failure"
        rm -f "$STAGED_FILE" 2>/dev/null || true; OUTCOME="failed"; return ;;
   esac
+  # A symbolic link on the working memory's path refuses the swap
+  # (D-HOOKS-NO-SYMLINK, git-marker): the run began without one, so a link there now
+  # is a change made during the run, and `mv` would move the staged memory into a
+  # folder it names. When the run began with no working memory, the cksum
+  # comparison below would take the link for that absent file.
+  if ! df_no_symlink_below "$PROJECT_ROOT" "$MEMORY_FILE"; then
+    rm -f "$STAGED_FILE" 2>/dev/null || true
+    log "CONFLICT: a symbolic link appeared on the path to $MEMORY_FILE during the run — not swapped, leaving .processing for retry"
+    OUTCOME="conflict"; return
+  fi
   # Re-check real file cksum before swapping.
   # Residual TOCTOU: a human edit landing in the O(ms) window between this
   # cksum re-check and the mv would be clobbered; this is accepted — the
@@ -613,14 +659,26 @@ verify_and_swap() {
 OUTCOME="failed"
 verify_and_swap
 
+# Each stamp below is a `touch`, which follows a symbolic link, and its path was
+# checked before the LLM run, which can take minutes. So, like the swap's target,
+# it is checked again just before the touch: a link there now is a change made
+# during the run, and the stamp is skipped and logged (D-HOOKS-NO-SYMLINK, git-marker).
 if [ "$OUTCOME" = "updated" ]; then
   rm -f "$PROCESSING_FILE" 2>/dev/null || true
-  touch "$OK_FILE" 2>/dev/null || true
-  log "SUCCESS: queue drained, .last-refresh-ok touched"
+  if df_no_symlink_below "$PROJECT_ROOT" "$OK_FILE"; then
+    touch "$OK_FILE" 2>/dev/null || true
+    log "SUCCESS: queue drained, .last-refresh-ok touched"
+  else
+    log "SUCCESS: queue drained; .last-refresh-ok not touched, a symbolic link appeared on its path during the run"
+  fi
 elif [ "$OUTCOME" = "conflict" ]; then
   # Heartbeat: this batch is still owned by the retry cycle, not orphaned.
   # Keeps session-start-memory's 300s cold path from reclaiming a live retry.
-  touch "$PROCESSING_FILE" 2>/dev/null || true
+  if df_no_symlink_below "$PROJECT_ROOT" "$PROCESSING_FILE"; then
+    touch "$PROCESSING_FILE" 2>/dev/null || true
+  else
+    log "Heartbeat skipped: a symbolic link appeared on the path to $PROCESSING_FILE during the run"
+  fi
   log "CONFLICT: queue retained in .processing, .last-refresh-ok untouched"
 else
   # Leave .processing for session-start-memory's D56c cold path; do NOT touch .last-refresh-ok

package/src/assets/scripts/hooks/capture-prompt

@@ -84,11 +84,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-prompt: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-prompt: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "user" "$PROMPT" "$TS"
 

package/src/assets/scripts/hooks/capture-question

@@ -140,8 +140,8 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-question: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-question: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 _QUESTION_COUNT=0
 while IFS=$'\t' read -r Q A; do
   [ -z "$Q" ] && continue
@@ -150,7 +150,8 @@ while IFS=$'\t' read -r Q A; do
 A: ${A}"
   TS=$(date +%s)
   queue_append_both \
-    "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+    "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+    "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
     "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
     "qa" "$CONTENT" "$TS"
   _QUESTION_COUNT=$(( _QUESTION_COUNT + 1 ))

package/src/assets/scripts/hooks/capture-turn

@@ -90,11 +90,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-turn: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-turn: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "assistant" "$ASSISTANT_MSG" "$TS"
 

package/src/assets/scripts/hooks/ensure-devflow-init

@@ -2,7 +2,8 @@
 # Ensures .devflow/ and all subdirectories exist and the project root .gitignore
 # ignores .devflow/. Called from capture-prompt, capture-turn, capture-question,
 # memory-worker, and pre-compact-memory. Idempotent.
-# Returns non-zero, having written nothing, outside a git project or at HOME.
+# Returns non-zero, having written nothing, outside a git project, at HOME, or when
+# .devflow is a symbolic link.
 # Usage: source ensure-devflow-init "$CWD"
 
 [ -z "$1" ] && return 1
@@ -33,6 +34,17 @@ df_is_project_root "$_EDI_ROOT" 2>/dev/null || return 1
 
 _DEVFLOW_DIR="$_EDI_ROOT/.devflow"
 
+# D-HOOKS-NO-SYMLINK (git-marker): a `.devflow` that is itself a symbolic link
+# would take every folder below and the carve-out marker into the folder it names,
+# so nothing is written and the caller stops, as at any root it may not write to.
+# The skip is logged once, through log() where the caller defines it. A folder below
+# `.devflow` that is a link is left to the write under it: `mkdir -p` creates
+# nothing through a link it ends at.
+if ! df_no_symlink_below "$_EDI_ROOT" "$_DEVFLOW_DIR"; then
+  declare -F log >/dev/null 2>&1 && log "Skipped: $_DEVFLOW_DIR is a symbolic link; nothing written under it"
+  return 1
+fi
+
 # learning/ is scaffolded only where the ledger lives. In a linked worktree whose
 # main checkout holds the ledger (D-LEDGER-MAIN-WORKTREE, resolve-project-root) a
 # learning/ here would be an empty directory nothing writes to; the capture hooks