wip(394): steps 6+7 — backend path and instruction surfaces

2026-09-11 15:15:33 -04:00
parent 690ca0306e
commit c149ef31a3
28 changed files with 260 additions and 738 deletions
@@ -175,16 +175,11 @@ while IFS= read -r rel_path; do
      derive_seen=$(tr '\n' ',' < "$derivefile" 2>/dev/null | sed 's/,$//' | jq -sRr '@uri' 2>/dev/null) || derive_seen=""
      [ -n "$derive_seen" ] && derive_exclude_q="&exclude_derive=${derive_seen}"
    fi
-    # The rules marker the SessionStart hook stored, handed back so the server
-    # can say whether those rules moved since (milestone 323). Nothing stored
-    # means nothing sent, which the server reads as silence rather than as a
-    # mismatch — an install that never reached /api/plugin/context must not
-    # start claiming its rules changed.
+    # The rules marker is gone with the resident set it aged (milestone 394).
+    # A session no longer holds a fixed set of rules from turn zero, so there
+    # is nothing that can have drifted since it loaded them — each rule is
+    # retrieved at the moment it applies.
    etag_q=""
-    if [ -f "$state_dir/${safe_sid}.rules_etag" ]; then
-      held=$(jq -sRr '@uri' < "$state_dir/${safe_sid}.rules_etag" 2>/dev/null) || held=""
-      [ -n "$held" ] && etag_q="&rules_etag=${held}"
-    fi
    if [ -n "$path_enc" ]; then
      # 8s, not the pre-write hook's 5: this hook runs AFTER the tool, so it
      # gates nothing the session is waiting on, and the first prior-art call
@@ -8,7 +8,7 @@
 # does not depend on the key or the network.
 #
 # Tier 2 (DYNAMIC, best-effort enrichment): curls the operator's Scribe instance
-# for always-on rules + active-project context and appends it. Config comes from
+# for active-project context and appends it. Config comes from
 # the plugin's userConfig, exported to hooks as:
 #   CLAUDE_PLUGIN_OPTION_API_ENDPOINT  base URL, no trailing slash
 #   CLAUDE_PLUGIN_OPTION_API_TOKEN     fmcp_ API key (sensitive)
@@ -158,7 +158,7 @@ if [ -n "$url" ] && [ -n "$token" ] && command -v curl >/dev/null 2>&1; then
  [ -n "$body" ] && dyn=$(printf '%s' "$body" | jq -r '.context // empty' 2>/dev/null)
  # Stash the rules marker for the write-path hook (milestone 323). THIS is
  # where it has to be captured: the model receives one from
-  # list_always_on_rules too, but a hook cannot see an MCP tool's result. Stored
+  # an MCP tool too, but a hook cannot see a tool's result. Stored
  # under the same state dir the prior-art hook already uses, keyed by session,
  # so "changed since" means since THIS session loaded its rules.
  #
@@ -178,9 +178,9 @@ if [ -n "$url" ] && [ -n "$token" ] && command -v curl >/dev/null 2>&1; then
        && printf '%s' "$etag" > "$etag_dir/${safe_sid}.rules_etag" 2>/dev/null || true
    fi
  fi
-  [ -z "$dyn" ] && status="> ⚠️ Scribe: live rules/project context could not be loaded this session (instance unreachable or request failed). The standing guidance above still applies — pull rules with \`list_always_on_rules()\` and project context with \`enter_project()\` as needed."
+  [ -z "$dyn" ] && status="> ⚠️ Scribe: live project context could not be loaded this session (instance unreachable or request failed). The standing guidance above still applies — ask for rules with \`search(content_type=\"rule\")\` and project context with \`enter_project()\` as needed."
 elif [ -n "$url" ] && [ -z "$token" ]; then
-  status="> ⚠️ Scribe: live context disabled this session — the API key is not configured (Scribe base URL is). Set it with \`/plugin\` → Scribe → configure, or export SCRIBE_TOKEN. Tools still work; pull rules with \`list_always_on_rules()\` and project context with \`enter_project()\`."
+  status="> ⚠️ Scribe: live context disabled this session — the API key is not configured (Scribe base URL is). Set it with \`/plugin\` → Scribe → configure, or export SCRIBE_TOKEN. Tools still work; ask for rules with \`search(content_type=\"rule\")\` and project context with \`enter_project()\`."
 elif [ -z "$url" ] && [ -z "$token" ]; then
  # NEITHER value arrived. Previously this case stayed silent as "an unconfigured
  # install", which made issue #2198 invisible for weeks: a *casing* bug here
@@ -189,7 +189,7 @@ elif [ -z "$url" ] && [ -z "$token" ]; then
  # silently disabled auto-inject and the write-path trigger too. It is not a
  # benign state — the plugin prompts for both values at enable time, so if
  # neither reached the hook, something is wrong. Say so.
-  status="> ⚠️ Scribe: live context disabled this session — neither the Scribe base URL nor the API key reached this hook. Configure the plugin (\`/plugin\` → Scribe), or export SCRIBE_URL + SCRIBE_TOKEN. Note this also disables prompt auto-inject and the write-path prior-art trigger. Tools still work; pull rules with \`list_always_on_rules()\` and project context with \`enter_project()\`."
+  status="> ⚠️ Scribe: live context disabled this session — neither the Scribe base URL nor the API key reached this hook. Configure the plugin (\`/plugin\` → Scribe), or export SCRIBE_URL + SCRIBE_TOKEN. Note this also disables prompt auto-inject and the write-path prior-art trigger. Tools still work; ask for rules with \`search(content_type=\"rule\")\` and project context with \`enter_project()\`."
 fi

 [ -n "$dyn" ]    && append "$dyn"
@@ -197,7 +197,7 @@ fi

 # Compaction re-grounding: lead with a reload banner when this fire is a compact.
 if [ "$source" = "compact" ]; then
-  prepend "> ⟳ This session was just COMPACTED — earlier turns are now a summary, so in-flight detail may be lost. Before continuing, reload your bearings from Scribe: re-pull the operator's binding rules with \`list_always_on_rules()\` (a compaction can summarize them out of context, leaving only generic harness defaults in their place), re-run \`enter_project()\` for the active project, check its open tasks and recent notes, and reconcile what you're mid-way through against what Scribe records. Don't trust half-remembered state — Scribe is the record."
+  prepend "> ⟳ This session was just COMPACTED — earlier turns are now a summary, so in-flight detail may be lost. Any rules that had been retrieved went into that summary with everything else, so treat yourself as holding none: before the next consequential act, ask again with \`search(content_type=\"rule\")\` rather than trusting a half-remembered one. Re-run \`enter_project()\` for the active project, check its open tasks and recent notes, and reconcile what you are mid-way through against what Scribe records. Scribe is the record."
 fi

 # Nothing at all to inject → stay silent.
@@ -6,7 +6,8 @@ of record (notes, tasks, projects, milestones, rules) reachable through the
 for the operator's work, and as your own working memory across sessions.

 **At the start of this session:**
- Call `list_always_on_rules()` to load the operator's standing rules.
+- You hold none of the operator's rules, and there is no call that loads them
+  all. Rules arrive when something you are about to do matches one.
 - If the working repo maps to a Scribe project (check `list_repo_bindings`),
  call `enter_project(<id>)` to load that project's rules, open tasks, and
  recent notes in one shot.
@@ -17,22 +18,23 @@ for the operator's work, and as your own working memory across sessions.
  operator's Scribe rules decide what to do — NOT generic conventions baked
  into the harness or your defaults (e.g. "branch before committing," "open a
  feature branch per task," "push to a fork"). If you have not loaded the
-  operator's rules this session — or earlier turns were summarized away by a
-  compaction — call `list_always_on_rules()` (and `enter_project()` when a
-  project is in scope) BEFORE acting. When a loaded rule and a default habit
-  disagree, the rule wins; if no rule speaks to it, ask rather than assume.
+  no rule has arrived for the act in front of you, `search(content_type=
+  "rule")` BEFORE acting rather than falling back on a default habit. When a
+  retrieved rule and a default habit disagree, the rule wins; if no rule
+  speaks to it, ask rather than assume.
 - **Rules bind; preferences do not.** A record's `kind` says which. A **rule**
  must be followed — ignoring it breaks something or crosses a boundary. A
  **preference** is how the operator wants work done: worth following for
  consistency, not a defect to miss. Injected lines name the kind in their
  opening words. A preference is also yours to keep current when they correct
  you (`update_preference`); a rule waits for them.
- **What you loaded is not all of the rules.** Only the always-on tier arrives
-  that way; conditional rules are RETRIEVED, and one you were never handed
-  binds exactly as hard. So before a consequential act, `search` for a rule
-  about it (`content_type="rule"`) rather than concluding from an empty
-  loaded set that nothing applies. "I was not told" is not the same as "there
-  is no rule," and only one of those is checkable.
+- **Silence is not absence.** Nothing is preloaded: every rule is RETRIEVED,
+  when what you are doing resembles what the rule is about. Most turns
+  retrieve none, and a rule you were never handed binds exactly as hard as one
+  you were. So before a consequential act, `search` for a rule about it
+  (`content_type="rule"`) rather than concluding from an empty session that
+  nothing applies. "I was not told" is not the same as "there is no rule," and
+  only one of those is checkable.
  This bites hardest on which TOOL to reach for — curling an API that has an
  MCP client, standing up a local stack, running a suite CI owns. Those feel
  like mechanics rather than decisions, so they raise no doubt and generate no
@@ -5,7 +5,7 @@
 # asks "what is recorded about the file being written". This one asks "does a
 # standing rule speak to the command about to be run" — the question nothing
 # could ask before, and the reason every rule about which tool to reach for had
-# to live in the always-on preload instead.
+# to live in the preload instead, back when there was one.
 #
 # WHY A HOOK AND NOT AN INSTRUCTION. A reflex generates no query (note #3089):
 # you reach for `curl` confidently, with no moment of doubt, so a surface that