@shardworks/astrolabe-apparatus 0.1.273 → 0.1.275

package/dist/engines/plan-finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-finalize.d.ts","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAqB3C,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA6ExF"}
+{"version":3,"file":"plan-finalize.d.ts","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAmB3C,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA6ExF"}

package/dist/engines/plan-finalize.js

@@ -38,14 +38,11 @@ const FRAMEWORK_EMITTER = 'framework';
  * installed (astrolabe declares clockworks in `recommends`, not
  * `requires`). Mirrors the lazy resolution `summon()` and the animator's
  * `tryResolveClockworks` use for `LoomApi` and `ClockworksApi`.
+ * Delegates to the framework's `tryApparatus<T>` primitive — the
+ * optional-dependency counterpart to `apparatus<T>`.
  */
 function tryResolveClockworks() {
-    try {
-        return guild().apparatus('clockworks');
-    }
-    catch {
-        return null;
-    }
+    return guild().tryApparatus('clockworks');
 }
 export function createPlanFinalizeEngine(getPlansBook) {
     return {

package/dist/engines/plan-finalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-finalize.js","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-finalize.js","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/astrolabe-apparatus",
-  "version": "0.1.273",
+  "version": "0.1.275",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -20,18 +20,18 @@
   },
   "dependencies": {
     "zod": "4.3.6",
-    "@shardworks/stacks-apparatus": "0.1.273",
-    "@shardworks/tools-apparatus": "0.1.273",
-    "@shardworks/spider-apparatus": "0.1.273",
-    "@shardworks/fabricator-apparatus": "0.1.273",
-    "@shardworks/clerk-apparatus": "0.1.273",
-    "@shardworks/loom-apparatus": "0.1.273",
-    "@shardworks/clockworks-apparatus": "0.1.273",
-    "@shardworks/animator-apparatus": "0.1.273"
+    "@shardworks/tools-apparatus": "0.1.275",
+    "@shardworks/stacks-apparatus": "0.1.275",
+    "@shardworks/clerk-apparatus": "0.1.275",
+    "@shardworks/spider-apparatus": "0.1.275",
+    "@shardworks/fabricator-apparatus": "0.1.275",
+    "@shardworks/clockworks-apparatus": "0.1.275",
+    "@shardworks/animator-apparatus": "0.1.275",
+    "@shardworks/loom-apparatus": "0.1.275"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
-    "@shardworks/nexus-core": "0.1.273"
+    "@shardworks/nexus-core": "0.1.275"
   },
   "files": [
     "dist",

package/pages/astrolabe/astrolabe.js

@@ -15,6 +15,37 @@
   var LIMIT = 20;
   var writTitleLookup = {};
 
+  // ── URL handling ───────────────────────────────────────────────────────
+
+  /**
+   * Read the current querystring as a `URLSearchParams`. Live snapshot
+   * — read at call time, never cached.
+   */
+  function currentUrlParams() {
+    return new URLSearchParams(window.location.search);
+  }
+
+  /**
+   * Apply the given key/value changes to the current querystring and
+   * `pushState` the result. Null/undefined/empty value deletes the key.
+   * Mirrors Ratchet's `updateUrl` (D9). The plan param shape (?plan=ID)
+   * is preserved verbatim — operators have URLs in the wild already
+   * (D10).
+   */
+  function updateUrl(changes) {
+    var params = currentUrlParams();
+    var keys = Object.keys(changes);
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      var value = changes[key];
+      if (value === null || value === undefined || value === '') params.delete(key);
+      else params.set(key, value);
+    }
+    var qs = params.toString();
+    var next = window.location.pathname + (qs ? '?' + qs : '');
+    window.history.pushState({}, '', next);
+  }
+
   // ── Utility ────────────────────────────────────────────────────────────
 
   function esc(s) {
@@ -299,11 +330,41 @@
 
   // ── Detail View ────────────────────────────────────────────────────────
 
-  function showPlanDetail(plan) {
+  /**
+   * Render a "not found" empty state inside the plan detail view for a
+   * deep-linked id that does not resolve. Per D16 the URL param is
+   * preserved so the operator can recover (correct the id, hit Back).
+   * Replaces the legacy fall-back-to-list behaviour, which silently
+   * dropped the param and pretended the deep-link never happened.
+   */
+  function renderPlanDetailNotFound(planId) {
+    currentPlan = null;
+    listView.style.display = 'none';
+    detailView.style.display = '';
+    detailTitle.textContent = 'Plan not found';
+    metaCard.innerHTML =
+      '<div class="empty-state" style="padding:1.5rem">' +
+      'No plan with id <code>' + esc(planId) + '</code> exists. ' +
+      'It may have been deleted, or the id may be mistyped.</div>';
+    // Hide tab content / decisions table — they reference fields on a
+    // missing plan that would just render blanks.
+    var tabContent = document.getElementById('tab-content');
+    if (tabContent) tabContent.innerHTML = '';
+  }
+
+  function showPlanDetail(plan, opts) {
+    var skipUrlPush = !!(opts && opts.skipUrlPush);
     currentPlan = plan;
     listView.style.display = 'none';
     detailView.style.display = '';
 
+    // Centralised URL push — every entry path into showPlanDetail
+    // (row click, deep-link init, popstate-driven re-open) emits
+    // ?plan=ID for free. The popstate-driven path passes
+    // skipUrlPush=true to avoid double-pushing the URL the browser
+    // already updated.
+    if (!skipUrlPush) updateUrl({ plan: plan.id });
+
     detailTitle.textContent = 'Plan: ' + plan.id;
 
     // Metadata card
@@ -605,39 +666,67 @@
 
   // ── Navigation ─────────────────────────────────────────────────────────
 
-  function backToList() {
+  function backToList(opts) {
+    var skipUrlPush = !!(opts && opts.skipUrlPush);
     detailView.style.display = 'none';
     listView.style.display = '';
     currentPlan = null;
+    // D11: push a clean URL — the operator's Forward button still does
+    // what they expect, and we never pop history because they may have
+    // arrived directly at ?plan=ID with no prior list-view entry.
+    if (!skipUrlPush) updateUrl({ plan: null });
   }
 
   // ── Deep Link ──────────────────────────────────────────────────────────
 
-  function handleDeepLink() {
-    var params = new URLSearchParams(window.location.search);
-    var planId = params.get('plan');
+  /**
+   * Resolve `?plan=ID` to a detail view. Called on init and from the
+   * popstate handler. Both paths suppress the URL push (the browser
+   * already has the URL in place, or the deep-link landed already).
+   * A missing/deleted/mistyped id renders the not-found empty state
+   * (D16) — the URL param is left intact.
+   *
+   * `opts.fetchOnEmpty` selects what to do when no plan param is
+   * present. Init wants the list to be fetched (this is the page's
+   * normal load); popstate just wants to switch back to whatever was
+   * already rendered.
+   */
+  function handleDeepLink(opts) {
+    var fetchOnEmpty = !(opts && opts.fetchOnEmpty === false);
+    var planId = currentUrlParams().get('plan');
 
     if (planId) {
-      // Deep link: fetch and show the specific plan
       fetch('/api/plan/show?planId=' + encodeURIComponent(planId))
         .then(function (r) {
           if (!r.ok) throw new Error('HTTP ' + r.status);
           return r.json();
         })
         .then(function (plan) {
-          showPlanDetail(plan);
+          showPlanDetail(plan, { skipUrlPush: true });
         })
         .catch(function (err) {
           console.error('Deep-link plan not found:', planId, err);
-          // Fallback: show list view
-          fetchPlans(true);
+          // D16: surface the failure as a not-found empty state inside
+          // the detail panel; never silently rewrite the URL.
+          renderPlanDetailNotFound(planId);
         });
-    } else {
+    } else if (fetchOnEmpty) {
       fetchPlans(true);
+    } else {
+      // popstate to a no-?plan URL: just return to the list view
+      // without re-fetching.
+      backToList({ skipUrlPush: true });
     }
   }
 
   // ── Init ───────────────────────────────────────────────────────────────
 
+  // popstate listener — the browser updated the URL, so we re-run the
+  // deep-link routing without re-pushing. Pairs with the central push
+  // inside showPlanDetail (D11/D12).
+  window.addEventListener('popstate', function () {
+    handleDeepLink({ fetchOnEmpty: false });
+  });
+
   handleDeepLink();
 })();

package/pages/astrolabe/astrolabe.test.js

@@ -708,3 +708,101 @@ describe('astrolabe.js cost-panel rig lookup uses rig-for-writ', () => {
     );
   });
 });
+
+// ── Deep-link URL state (?plan=ID) ──────────────────────────────────────
+
+describe('astrolabe.js — deep-link URL state', () => {
+  it('exposes currentUrlParams + updateUrl helpers (D9 — Ratchet pattern)', () => {
+    assert.match(
+      astrolabeJs,
+      /function currentUrlParams\(\)\s*\{[\s\S]*?new URLSearchParams\(window\.location\.search\)/,
+      'currentUrlParams reads window.location.search live',
+    );
+    assert.match(
+      astrolabeJs,
+      /function updateUrl\(changes\)\s*\{[\s\S]*?window\.history\.pushState/,
+      'updateUrl pushes via history.pushState',
+    );
+  });
+
+  it('showPlanDetail pushes ?plan=ID via the central updateUrl call (D12)', () => {
+    const block = astrolabeJs.match(
+      /function showPlanDetail\(plan(?:, opts)?\)[\s\S]*?(?=\n {2}function )/,
+    );
+    assert.ok(block, 'should find showPlanDetail body');
+    assert.match(
+      block[0],
+      /updateUrl\(\{\s*plan:\s*plan\.id\s*\}\)/,
+      'showPlanDetail should push ?plan=<plan.id> when not skipUrlPush',
+    );
+    assert.match(block[0], /skipUrlPush/, 'showPlanDetail accepts a skipUrlPush opt');
+  });
+
+  it('backToList clears ?plan via updateUrl({plan: null}) — never pops history (D11)', () => {
+    const block = astrolabeJs.match(
+      /function backToList\((?:opts)?\)[\s\S]*?(?=\n {2}\/\/)/,
+    );
+    assert.ok(block, 'should find backToList body');
+    assert.match(
+      block[0],
+      /updateUrl\(\{\s*plan:\s*null\s*\}\)/,
+      'backToList should push a clean URL via updateUrl({plan: null})',
+    );
+    assert.ok(
+      !/window\.history\.back\s*\(/.test(block[0]),
+      'backToList should never invoke history.back',
+    );
+  });
+
+  it('a popstate listener re-runs handleDeepLink without re-pushing the URL', () => {
+    assert.match(
+      astrolabeJs,
+      /window\.addEventListener\(\s*['"]popstate['"]/,
+      'astrolabe.js registers a popstate listener',
+    );
+    const block = astrolabeJs.match(
+      /addEventListener\(\s*['"]popstate['"][\s\S]*?\}\)/,
+    );
+    assert.ok(block, 'should find popstate handler body');
+    assert.match(
+      block[0],
+      /handleDeepLink\(\{\s*fetchOnEmpty:\s*false\s*\}\)/,
+      'popstate handler invokes handleDeepLink with fetchOnEmpty=false',
+    );
+  });
+
+  it('handleDeepLink renders a not-found state instead of falling back to the list (D16)', () => {
+    const block = astrolabeJs.match(
+      /function handleDeepLink\([\s\S]*?(?=\n {2}\/\/ ── Init)/,
+    );
+    assert.ok(block, 'should find handleDeepLink body');
+    assert.match(
+      block[0],
+      /renderPlanDetailNotFound\(planId\)/,
+      'handleDeepLink should render the not-found state on fetch failure',
+    );
+    // The deep-link calls into showPlanDetail with skipUrlPush so we
+    // don't double-push the URL the operator already arrived with.
+    assert.match(
+      block[0],
+      /showPlanDetail\(plan,\s*\{\s*skipUrlPush:\s*true\s*\}\)/,
+      'init / popstate path passes skipUrlPush=true into showPlanDetail',
+    );
+  });
+
+  it('renderPlanDetailNotFound preserves the URL param', () => {
+    const block = astrolabeJs.match(
+      /function renderPlanDetailNotFound\([\s\S]*?(?=\n {2}function )/,
+    );
+    assert.ok(block, 'should find renderPlanDetailNotFound body');
+    assert.ok(
+      !/updateUrl/.test(block[0]),
+      'renderPlanDetailNotFound must not rewrite the URL',
+    );
+    assert.match(
+      block[0],
+      /No plan with id/,
+      'renderPlanDetailNotFound surfaces a "not found" message',
+    );
+  });
+});

package/sage-primer-attended.md

@@ -43,7 +43,7 @@ You also have the standard file-reading tools (Read, Glob, Grep) for exploring t
 3. Write the codebase inventory using `inventory-write`. The inventory must meet the full quality bar described below.
 4. Write scope items using `scope-write`. Break the brief into coarse, independently deliverable capabilities. Each item should be something the patron might include or exclude.
 5. Write decisions using `decisions-write`. Be exhaustive — capture every design question including ones where the answer seems obvious from codebase conventions. Each decision needs: id, scope references, question, context, options, recommendation, rationale, and `selected`. Pre-fill `selected` on every decision — use brief pre-emption and suggestion rules where they apply, and apply the Three Defaults everywhere else. Never set `patronOverride` — that field is owned by the patron-review pass. When you feel uncertainty about any decision, treat that feeling as a cue to **investigate** — read more code, trace another caller, check the brief again — not as a cue to leave `selected` unset.
-6. Write observations using `observations-write`. Record refactoring opportunities, risks, suboptimal conventions, doc/code discrepancies, and potential bugs noticed during your pass.
+6. Write observations using `observations-write`. **Apply the discriminating bar in the *Observations* section below** — every record you lift will be auto-promoted to a draft writ, so the bar for "this deserves an observation" is high. Doc drift on touched files is NOT an observation (note it in the inventory as "concurrent doc updates needed" instead). Brief meta-observations and future-feature placeholders are NOT observations.
 
 You may interleave reading and writing — for example, write partial inventory as you go and refine it, or write scope items as they become clear and adjust later. The key constraint is that when you finish, all four artifacts (inventory, scope, decisions, observations) must be complete and written to the plan via the write tools.
 
@@ -92,7 +92,8 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - Any prior commissions that touched this code (check commission log if relevant)
 
 **Doc/code discrepancies:**
-- Note any places where documentation describes different behavior than the code implements. These may indicate bugs, stale docs, or unfinished migrations. Don't try to resolve them — just record them.
+- Note any places where documentation describes different behavior than the code implements. Capture them in the inventory as data points; do NOT lift to observations unless they meet the *Observations* bar (real bug, real cross-cutting design Q, real consolidation, real hidden-migration evidence).
+- **Tag drift on files the commission will already be touching as `concurrent doc updates needed`** — the implementing artificer will fix this inline as part of the work. Do not separately lift it as an observation.
 
 This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced) and analytical orientation (downstream agents can form decisions from your map), not in transcribing code.
 
@@ -185,12 +186,24 @@ Order decisions by scope item.
 
 ### Observations
 
-Accumulate a punch list of things noticed during your pass that are outside the brief's scope but worth recording:
+Observations are concerns worth lifting to a draft mandate writ for downstream curator review. Each observation gets auto-promoted to a draft writ, so the bar for what counts as an observation must be high — anything you lift will sit in the books until a curator triages it.
 
-- **Refactoring opportunities** skipped to keep scope narrow
-- **Suboptimal conventions** followed for consistency
-- **Doc/code discrepancies** found during inventory
-- **Potential bugs or risks** noticed in adjacent code
+**An observation is the right primitive when one of these is true:**
+
+- **Real bug or latent hazard.** A code path that's wrong, a race that's possible, an edge case that will silently misbehave, a contract gap downstream consumers will trip over.
+- **Real cross-cutting design question.** A decision that needs to be made because two or more apparatuses will trip over it. Not a question for *this* commission (those are decisions, not observations) but one that surfaces during this pass and deserves its own thread.
+- **Real DRY/consolidation opportunity with concrete payoff.** Duplicated logic across N call sites with measurable maintenance cost. Not "this could be cleaner" but "this WILL drift and bite us."
+- **Doc/code discrepancy that points at a hidden bug or unfinished migration.** Where the gap implies the migration was abandoned mid-way or a behavior was changed without updating callers.
+
+**An observation is NOT the right primitive for any of these:**
+
+- **Doc drift on files inside or adjacent to your touched area.** Surface in inventory under "concurrent doc updates needed" so the implementing artificer fixes it inline. Stale text in `clockworks.md` while the commission is already editing `clockworks.md` is part of the work, not a follow-up.
+- **Doc drift on files far outside your touched area.** Let the next commission that touches them fix the drift. Doc drift is largely self-healing through normal traffic.
+- **Brief meta-observations.** "The brief cites stale line numbers" / "the brief mislocates X." These are observations about the staleness of the planning artifact, which becomes archival once the commission ships. Do not lift.
+- **Future-feature placeholders.** "Someone should commission X downstream." Track those as clicks under the appropriate subtree, not as observation writs.
+- **Nice-to-have UX or polish** without observed friction. Wait for a real operator/anima to hit the issue.
+
+When in doubt about whether to lift, ask: *"Could the artificer of this commission realistically address this inline?"* If yes, surface it in the inventory rather than as an observation. *"Will this self-heal as someone touches the area next?"* If yes, do not lift.
 
 Each observation is **one record per atomic concern**. Downstream, the `astrolabe.observation-lift` engine lifts each record into a draft top-level `mandate` writ (never a child of the originating mandate); each lifted writ carries an `astrolabe.lifted-from` provenance edge back to the originating mandate, plus a `spider.follows` edge that holds dispatch until the mandate has terminated. When the plan yields two or more observations, the engine additionally groups them under a top-level `observation-set` container that parents the draft mandates and carries the `astrolabe.lifted-from` edge on behalf of the batch. A curator (human or automated) promotes each draft to open status. Your job is to package the concerns; you do not decide which ones get promoted.
 

package/sage-primer-reader.md

@@ -60,7 +60,8 @@ Your inventory feeds a downstream scoping primer and spec writer who produce **i
 - Any prior commissions that touched this code (check commission log if relevant)
 
 **Doc/code discrepancies:**
-- Note any places where documentation describes different behavior than the code implements. These may indicate bugs, stale docs, or unfinished migrations. Don't try to resolve them — just record them.
+- Note any places where documentation describes different behavior than the code implements. Capture them in the inventory as data points; downstream primer stages will decide whether any rise to the bar of being a separately-lifted observation.
+- **Tag drift on files the commission will already be touching as `concurrent doc updates needed`** — the implementing artificer will fix this inline as part of the work, no separate observation needed.
 
 **Click references in the brief:**
 - Briefs frequently reference clicks by id (long form `c-mo2e88aw-f4d5684cf385` or short form `c-mo301yp9`). Clicks are the guild's record of decisions and open inquiries, managed by the Ratchet apparatus. Treat click references as mandatory context — same priority as reading referenced source files.

package/sage-primer-scoping.md

@@ -181,12 +181,24 @@ Write all decisions using `decisions-write`.
 
 ### Step 3: Observations
 
-Accumulate a punch list of things noticed during analysis that are outside the brief's scope but worth recording:
+Observations are concerns worth lifting to a draft mandate writ for downstream curator review. Each observation gets auto-promoted to a draft writ, so the bar for what counts as an observation must be high — anything you lift will sit in the books until a curator triages it.
 
-- **Refactoring opportunities** skipped to keep scope narrow
-- **Suboptimal conventions** followed for consistency
-- **Doc/code discrepancies** found during inventory
-- **Potential bugs or risks** noticed in adjacent code
+**An observation is the right primitive when one of these is true:**
+
+- **Real bug or latent hazard.** A code path that's wrong, a race that's possible, an edge case that will silently misbehave, a contract gap downstream consumers will trip over.
+- **Real cross-cutting design question.** A decision that needs to be made because two or more apparatuses will trip over it. Not a question for *this* commission (those are decisions, not observations) but one that surfaces during this pass and deserves its own thread.
+- **Real DRY/consolidation opportunity with concrete payoff.** Duplicated logic across N call sites with measurable maintenance cost. Not "this could be cleaner" but "this WILL drift and bite us."
+- **Doc/code discrepancy that points at a hidden bug or unfinished migration.** Where the gap implies the migration was abandoned mid-way or a behavior was changed without updating callers.
+
+**An observation is NOT the right primitive for any of these:**
+
+- **Doc drift on files inside or adjacent to your touched area.** Surface in inventory under "concurrent doc updates needed" so the implementing artificer fixes it inline. Stale text in `clockworks.md` while the commission is already editing `clockworks.md` is part of the work, not a follow-up.
+- **Doc drift on files far outside your touched area.** Let the next commission that touches them fix the drift. Doc drift is largely self-healing through normal traffic.
+- **Brief meta-observations.** "The brief cites stale line numbers" / "the brief mislocates X." These are observations about the staleness of the planning artifact, which becomes archival once the commission ships. Do not lift.
+- **Future-feature placeholders.** "Someone should commission X downstream." Track those as clicks under the appropriate subtree, not as observation writs.
+- **Nice-to-have UX or polish** without observed friction. Wait for a real operator/anima to hit the issue.
+
+When in doubt about whether to lift, ask: *"Could the artificer of this commission realistically address this inline?"* If yes, surface it in the inventory rather than as an observation. *"Will this self-heal as someone touches the area next?"* If yes, do not lift.
 
 Each observation is **one record per atomic concern**. Downstream, the `astrolabe.observation-lift` engine lifts each record into a draft top-level `mandate` writ (never a child of the originating mandate); each lifted writ carries an `astrolabe.lifted-from` provenance edge back to the originating mandate, plus a `spider.follows` edge that holds dispatch until the mandate has terminated. When the plan yields two or more observations, the engine additionally groups them under a top-level `observation-set` container that parents the draft mandates and carries the `astrolabe.lifted-from` edge on behalf of the batch. A curator (human or automated) promotes each draft to open status. Your job is to package the concerns; you do not decide which ones get promoted.
 

package/sage-primer-solo.md

@@ -43,7 +43,7 @@ You also have the standard file-reading tools (Read, Glob, Grep) for exploring t
 3. Write the codebase inventory using `inventory-write`. The inventory must meet the full quality bar described below.
 4. Write scope items using `scope-write`. Break the brief into coarse, independently deliverable capabilities. Each item should be something the patron might include or exclude.
 5. Write decisions using `decisions-write`. Be exhaustive — capture every design question including ones where the answer seems obvious from codebase conventions. Each decision needs: id, scope references, question, context, options, recommendation, rationale, and `selected` (see the pre-fill rule under Decision Analysis — leave unset only when the decision matches the razor and passes the Reach and Patch Tests; otherwise apply the three defaults and pre-fill with your choice). Never set `patronOverride` — that field is owned by the patron-review pass. When you feel uncertainty about a decision that does *not* match any razor criterion, treat that feeling as a cue to **investigate** — read more code, trace another caller, check the brief again — not as a cue to punt the decision to the patron.
-6. Write observations using `observations-write`. Record refactoring opportunities, risks, suboptimal conventions, doc/code discrepancies, and potential bugs noticed during your pass.
+6. Write observations using `observations-write`. **Apply the discriminating bar in the *Observations* section below** — every record you lift will be auto-promoted to a draft writ, so the bar for "this deserves an observation" is high. Doc drift on touched files is NOT an observation (note it in the inventory as "concurrent doc updates needed" instead). Brief meta-observations and future-feature placeholders are NOT observations.
 
 You may interleave reading and writing — for example, write partial inventory as you go and refine it, or write scope items as they become clear and adjust later. The key constraint is that when you finish, all four artifacts (inventory, scope, decisions, observations) must be complete and written to the plan via the write tools.
 
@@ -92,7 +92,8 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - Any prior commissions that touched this code (check commission log if relevant)
 
 **Doc/code discrepancies:**
-- Note any places where documentation describes different behavior than the code implements. These may indicate bugs, stale docs, or unfinished migrations. Don't try to resolve them — just record them.
+- Note any places where documentation describes different behavior than the code implements. Capture them in the inventory as data points; do NOT lift to observations unless they meet the *Observations* bar (real bug, real cross-cutting design Q, real consolidation, real hidden-migration evidence).
+- **Tag drift on files the commission will already be touching as `concurrent doc updates needed`** — the implementing artificer will fix this inline as part of the work. Do not separately lift it as an observation.
 
 This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced) and analytical orientation (downstream agents can form decisions from your map), not in transcribing code.
 
@@ -216,12 +217,24 @@ Order decisions by scope item.
 
 ### Observations
 
-Accumulate a punch list of things noticed during your pass that are outside the brief's scope but worth recording:
+Observations are concerns worth lifting to a draft mandate writ for downstream curator review. Each observation gets auto-promoted to a draft writ, so the bar for what counts as an observation must be high — anything you lift will sit in the books until a curator triages it.
 
-- **Refactoring opportunities** skipped to keep scope narrow
-- **Suboptimal conventions** followed for consistency
-- **Doc/code discrepancies** found during inventory
-- **Potential bugs or risks** noticed in adjacent code
+**An observation is the right primitive when one of these is true:**
+
+- **Real bug or latent hazard.** A code path that's wrong, a race that's possible, an edge case that will silently misbehave, a contract gap downstream consumers will trip over.
+- **Real cross-cutting design question.** A decision that needs to be made because two or more apparatuses will trip over it. Not a question for *this* commission (those are decisions, not observations) but one that surfaces during this pass and deserves its own thread.
+- **Real DRY/consolidation opportunity with concrete payoff.** Duplicated logic across N call sites with measurable maintenance cost. Not "this could be cleaner" but "this WILL drift and bite us."
+- **Doc/code discrepancy that points at a hidden bug or unfinished migration.** Where the gap implies the migration was abandoned mid-way or a behavior was changed without updating callers.
+
+**An observation is NOT the right primitive for any of these:**
+
+- **Doc drift on files inside or adjacent to your touched area.** Surface in inventory under "concurrent doc updates needed" so the implementing artificer fixes it inline. Stale text in `clockworks.md` while the commission is already editing `clockworks.md` is part of the work, not a follow-up.
+- **Doc drift on files far outside your touched area.** Let the next commission that touches them fix the drift. Doc drift is largely self-healing through normal traffic.
+- **Brief meta-observations.** "The brief cites stale line numbers" / "the brief mislocates X." These are observations about the staleness of the planning artifact, which becomes archival once the commission ships. Do not lift.
+- **Future-feature placeholders.** "Someone should commission X downstream." Track those as clicks under the appropriate subtree, not as observation writs.
+- **Nice-to-have UX or polish** without observed friction. Wait for a real operator/anima to hit the issue.
+
+When in doubt about whether to lift, ask: *"Could the artificer of this commission realistically address this inline?"* If yes, surface it in the inventory rather than as an observation. *"Will this self-heal as someone touches the area next?"* If yes, do not lift.
 
 Each observation is **one record per atomic concern**. Downstream, the `astrolabe.observation-lift` engine lifts each record into a draft top-level `mandate` writ (never a child of the originating mandate); each lifted writ carries an `astrolabe.lifted-from` provenance edge back to the originating mandate, plus a `spider.follows` edge that holds dispatch until the mandate has terminated. When the plan yields two or more observations, the engine additionally groups them under a top-level `observation-set` container that parents the draft mandates and carries the `astrolabe.lifted-from` edge on behalf of the batch. A curator (human or automated) promotes each draft to open status. Your job is to package the concerns; you do not decide which ones get promoted.