@karmaniverous/jeeves-meta-openclaw 0.10.7 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,9 +4,10 @@ OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that register
4
4
 
5
5
  ## Features
6
6
 
7
- - **Eleven tools** — standard: `meta_status`, `meta_config`, `meta_config_apply`, `meta_service`; custom: `meta_list`, `meta_detail`, `meta_trigger`, `meta_preview`, `meta_seed`, `meta_unlock`, `meta_queue` (list/clear/abort)
7
+ - **Twelve tools** — standard: `meta_status`, `meta_config`, `meta_config_apply`, `meta_service`; custom: `meta_list`, `meta_detail`, `meta_trigger`, `meta_preview`, `meta_seed`, `meta_unlock`, `meta_queue` (list/clear/abort), `meta_update`
8
8
  - **MetaServiceClient** — typed HTTP client delegating all operations to the running service
9
- - **TOOLS.md injection** — periodic refresh of entity stats via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
9
+ - **TOOLS.md injection** — periodic refresh of entity stats, phase-state summary, failed-phase alerts, and next-phase indicator via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
10
+ - **Phase-state awareness** — tools expose per-meta `_phaseState`, `owedPhase`, and phase-state summary from the service's phase-state machine
10
11
  - **Cleanup escalation** — passes `gatewayUrl` into `ComponentWriter` so managed-content cleanup can request a gateway session when needed
11
12
  - **Dependency health** — shows warnings when watcher/gateway are degraded
12
13
  - **Consumer skill** — `SKILL.md` for agent integration
@@ -57,7 +58,7 @@ The `configRoot` setting tells `@karmaniverous/jeeves` core where to find the pl
57
58
  ## Documentation
58
59
 
59
60
  - **[Plugin Setup](guides/plugin-setup.md)** — installation, config, lifecycle
60
- - **[Tools Reference](guides/tools-reference.md)** — 11 tools: standard (meta_status, meta_config, meta_config_apply, meta_service) + custom (meta_list, meta_detail, meta_trigger, meta_preview, meta_seed, meta_unlock, meta_queue)
61
+ - **[Tools Reference](guides/tools-reference.md)** — 12 tools: standard (meta_status, meta_config, meta_config_apply, meta_service) + custom (meta_list, meta_detail, meta_trigger, meta_preview, meta_seed, meta_unlock, meta_queue, meta_update)
61
62
  - **[Virtual Rules](guides/virtual-rules.md)** — watcher inference rules
62
63
  - **[TOOLS.md Injection](guides/tools-injection.md)** — dynamic prompt generation
63
64
 
package/dist/index.js CHANGED
@@ -18842,6 +18842,63 @@ async function generateMetaMenu(client) {
18842
18842
  if (dependencies.gateway.status !== 'ok') {
18843
18843
  depLines.push('> ⚠️ **Gateway**: ' + dependencies.gateway.status);
18844
18844
  }
18845
+ // Phase-state summary from /status health
18846
+ const phaseLines = [];
18847
+ const phaseSummary = status.health.phaseStateSummary;
18848
+ if (phaseSummary) {
18849
+ // Aggregate counts across all phases
18850
+ const totals = {};
18851
+ for (const phase of ['architect', 'builder', 'critic']) {
18852
+ const counts = phaseSummary[phase];
18853
+ for (const [state, count] of Object.entries(counts)) {
18854
+ if (count > 0) {
18855
+ totals[state] = (totals[state] ?? 0) + count;
18856
+ }
18857
+ }
18858
+ }
18859
+ const parts = [];
18860
+ for (const state of ['fresh', 'pending', 'running', 'failed']) {
18861
+ if (totals[state]) {
18862
+ parts.push(totals[state].toString() + ' ' + state);
18863
+ }
18864
+ }
18865
+ if (parts.length > 0) {
18866
+ phaseLines.push('Phases: ' + parts.join(', '));
18867
+ }
18868
+ // Failed-phase alert
18869
+ const failedParts = [];
18870
+ for (const item of metas.metas) {
18871
+ const ps = item.phaseState;
18872
+ if (!ps)
18873
+ continue;
18874
+ for (const phase of ['architect', 'builder', 'critic']) {
18875
+ if (ps[phase] === 'failed') {
18876
+ const p = item.path;
18877
+ failedParts.push(p + ' (' + phase + ')');
18878
+ }
18879
+ }
18880
+ }
18881
+ if (failedParts.length > 0) {
18882
+ phaseLines.push('> Failed: ' +
18883
+ failedParts.slice(0, 10).join(', ') +
18884
+ (failedParts.length > 10
18885
+ ? ' (+' + (failedParts.length - 10).toString() + ' more)'
18886
+ : ''));
18887
+ }
18888
+ }
18889
+ // Next-phase indicator from /status health
18890
+ const nextPhase = status.health.nextPhase;
18891
+ if (nextPhase) {
18892
+ phaseLines.push('Next: ' +
18893
+ nextPhase.path +
18894
+ ' → ' +
18895
+ nextPhase.phase +
18896
+ ' (band ' +
18897
+ nextPhase.band.toString() +
18898
+ ', staleness ' +
18899
+ formatAge(nextPhase.staleness) +
18900
+ ')');
18901
+ }
18845
18902
  return [
18846
18903
  'The jeeves-meta synthesis engine manages ' +
18847
18904
  summary.total.toString() +
@@ -18856,6 +18913,7 @@ async function generateMetaMenu(client) {
18856
18913
  '| Never synthesized | ' + summary.neverSynthesized.toString() + ' |',
18857
18914
  '| Stalest | ' + stalestDisplay + ' |',
18858
18915
  '| Last synthesized | ' + lastSynthDisplay + ' |',
18916
+ ...(phaseLines.length > 0 ? ['', '### Phase State', ...phaseLines] : []),
18859
18917
  ...(depLines.length > 0 ? ['', '### Dependencies', ...depLines] : []),
18860
18918
  '',
18861
18919
  'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
@@ -18905,11 +18963,22 @@ class MetaServiceClient {
18905
18963
  qs.set('neverSynthesized', String(params.neverSynthesized));
18906
18964
  if (params?.locked !== undefined)
18907
18965
  qs.set('locked', String(params.locked));
18966
+ if (params?.disabled !== undefined)
18967
+ qs.set('disabled', String(params.disabled));
18908
18968
  if (params?.fields?.length)
18909
18969
  qs.set('fields', params.fields.join(','));
18910
18970
  const query = qs.toString();
18911
18971
  return this.get('/metas' + (query ? '?' + query : ''));
18912
18972
  }
18973
+ /** PATCH /metas/:path — update user-settable reserved properties. */
18974
+ async update(metaPath, updates) {
18975
+ const encoded = encodeURIComponent(metaPath);
18976
+ return fetchJson(`${this.baseUrl}/metas/${encoded}`, {
18977
+ method: 'PATCH',
18978
+ headers: { 'Content-Type': 'application/json' },
18979
+ body: JSON.stringify(updates),
18980
+ });
18981
+ }
18913
18982
  /** GET /metas/:path — detail for a single meta. */
18914
18983
  async detail(metaPath, options) {
18915
18984
  const encoded = encodeURIComponent(metaPath);
@@ -18980,6 +19049,7 @@ function buildCustomTools(client, baseUrl) {
18980
19049
  buildMetaSeedTool(client, baseUrl),
18981
19050
  buildMetaUnlockTool(client, baseUrl),
18982
19051
  buildMetaQueueTool(client, baseUrl),
19052
+ buildMetaUpdateTool(client, baseUrl),
18983
19053
  ];
18984
19054
  }
18985
19055
  /** Wrap tool execution with connection error handling. */
@@ -18991,7 +19061,7 @@ function wrap(baseUrl, fn) {
18991
19061
  function buildMetaListTool(client, baseUrl) {
18992
19062
  return {
18993
19063
  name: 'meta_list',
18994
- description: 'List metas with summary stats and per-meta projection. Replaces meta_status + meta_entities.',
19064
+ description: 'List metas with summary stats and per-meta projection. Response includes _phaseState and owedPhase per meta.',
18995
19065
  parameters: {
18996
19066
  type: 'object',
18997
19067
  properties: {
@@ -19001,12 +19071,13 @@ function buildMetaListTool(client, baseUrl) {
19001
19071
  },
19002
19072
  filter: {
19003
19073
  type: 'object',
19004
- description: 'Structured filter. Supported keys: hasError (boolean), staleHours (number), neverSynthesized (boolean), locked (boolean).',
19074
+ description: 'Structured filter. Supported keys: hasError (boolean), staleHours (number), neverSynthesized (boolean), locked (boolean), disabled (boolean).',
19005
19075
  properties: {
19006
19076
  hasError: { type: 'boolean' },
19007
19077
  staleHours: { type: 'number' },
19008
19078
  neverSynthesized: { type: 'boolean' },
19009
19079
  locked: { type: 'boolean' },
19080
+ disabled: { type: 'boolean' },
19010
19081
  },
19011
19082
  },
19012
19083
  fields: {
@@ -19024,6 +19095,7 @@ function buildMetaListTool(client, baseUrl) {
19024
19095
  staleHours: filter?.staleHours,
19025
19096
  neverSynthesized: filter?.neverSynthesized,
19026
19097
  locked: filter?.locked,
19098
+ disabled: filter?.disabled,
19027
19099
  fields: params.fields,
19028
19100
  }));
19029
19101
  },
@@ -19032,7 +19104,7 @@ function buildMetaListTool(client, baseUrl) {
19032
19104
  function buildMetaDetailTool(client, baseUrl) {
19033
19105
  return {
19034
19106
  name: 'meta_detail',
19035
- description: 'Full detail for a single meta, with optional archive history.',
19107
+ description: 'Full detail for a single meta, with optional archive history. Response includes _phaseState and owedPhase.',
19036
19108
  parameters: {
19037
19109
  type: 'object',
19038
19110
  properties: {
@@ -19061,7 +19133,7 @@ function buildMetaDetailTool(client, baseUrl) {
19061
19133
  function buildMetaPreviewTool(client, baseUrl) {
19062
19134
  return {
19063
19135
  name: 'meta_preview',
19064
- description: 'Dry-run: show what inputs would be gathered for the next synthesis cycle without running LLM.',
19136
+ description: 'Dry-run preview of next synthesis. Returns owedPhase, priorityBand, phaseState, stalenessInputs, and architectInvalidators.',
19065
19137
  parameters: {
19066
19138
  type: 'object',
19067
19139
  properties: {
@@ -19077,7 +19149,7 @@ function buildMetaPreviewTool(client, baseUrl) {
19077
19149
  function buildMetaTriggerTool(client, baseUrl) {
19078
19150
  return {
19079
19151
  name: 'meta_trigger',
19080
- description: 'Manually trigger synthesis for a specific meta or the next-stalest candidate.',
19152
+ description: 'Trigger synthesis. Path-targeted creates an override queue entry; returns owedPhase. Fully-fresh metas return status:skipped.',
19081
19153
  parameters: {
19082
19154
  type: 'object',
19083
19155
  properties: {
@@ -19153,7 +19225,7 @@ function buildMetaUnlockTool(client, baseUrl) {
19153
19225
  function buildMetaQueueTool(client, baseUrl) {
19154
19226
  return {
19155
19227
  name: 'meta_queue',
19156
- description: 'Queue management: list pending items, clear the queue, or abort current synthesis.',
19228
+ description: 'Queue management. list: 3-layer model (current with phase, overrides, automatic, pending). clear: removes overrides only. abort: returns {status,path,phase} or {status:idle}.',
19157
19229
  parameters: {
19158
19230
  type: 'object',
19159
19231
  properties: {
@@ -19180,6 +19252,39 @@ function buildMetaQueueTool(client, baseUrl) {
19180
19252
  },
19181
19253
  };
19182
19254
  }
19255
+ function buildMetaUpdateTool(client, baseUrl) {
19256
+ return {
19257
+ name: 'meta_update',
19258
+ description: 'Update user-settable reserved properties on a meta entity.',
19259
+ parameters: {
19260
+ type: 'object',
19261
+ properties: {
19262
+ path: {
19263
+ type: 'string',
19264
+ description: 'Path to the .meta/ directory or owner directory.',
19265
+ },
19266
+ updates: {
19267
+ type: 'object',
19268
+ description: 'Properties to set. Supported: _steer, _emphasis, _depth, _crossRefs, _disabled. Set to null to remove.',
19269
+ properties: {
19270
+ _steer: { type: ['string', 'null'] },
19271
+ _emphasis: { type: ['number', 'null'] },
19272
+ _depth: { type: ['number', 'null'] },
19273
+ _crossRefs: {
19274
+ oneOf: [
19275
+ { type: 'array', items: { type: 'string' } },
19276
+ { type: 'null' },
19277
+ ],
19278
+ },
19279
+ _disabled: { type: ['boolean', 'null'] },
19280
+ },
19281
+ },
19282
+ },
19283
+ required: ['path', 'updates'],
19284
+ },
19285
+ execute: async (_id, params) => wrap(baseUrl, () => client.update(params.path, params.updates)),
19286
+ };
19287
+ }
19183
19288
 
19184
19289
  /**
19185
19290
  * Meta tool registrations for OpenClaw.
@@ -91,8 +91,17 @@ export declare class MetaServiceClient {
91
91
  staleHours?: number;
92
92
  neverSynthesized?: boolean;
93
93
  locked?: boolean;
94
+ disabled?: boolean;
94
95
  fields?: string[];
95
96
  }): Promise<MetasResponse>;
97
+ /** PATCH /metas/:path — update user-settable reserved properties. */
98
+ update(metaPath: string, updates: {
99
+ _steer?: string | null;
100
+ _emphasis?: number | null;
101
+ _depth?: number | null;
102
+ _crossRefs?: string[] | null;
103
+ _disabled?: boolean | null;
104
+ }): Promise<unknown>;
96
105
  /** GET /metas/:path — detail for a single meta. */
97
106
  detail(metaPath: string, options?: {
98
107
  includeArchive?: boolean | number;
@@ -7,6 +7,12 @@ jeeves-meta is the Jeeves platform's knowledge synthesis engine. It discovers
7
7
  gathers context from co-located source files, and uses a three-step LLM process
8
8
  (architect, builder, critic) to produce structured synthesis artifacts.
9
9
 
10
+ Each meta entity carries a **phase-state machine** (`_phaseState`) tracking
11
+ the state of each phase independently: `fresh`, `stale`, `pending`, `running`,
12
+ or `failed`. The scheduler picks **one phase per tick** across the entire
13
+ corpus (critic > builder > architect priority), enabling surgical retries of
14
+ failed phases without re-running the full pipeline.
15
+
10
16
  **Requires:** jeeves-watcher ≥ 0.10.0 (provides `POST /walk` and auto
11
17
  rules-reindex on registration).
12
18
 
@@ -19,16 +25,19 @@ registration health.
19
25
 
20
26
  ### meta_list
21
27
  List all `.meta/` directories with summary stats and per-meta projection.
22
- Supports filtering by path prefix, error status, staleness, and lock state.
23
- Use for engine health checks and finding stale knowledge.
28
+ Supports filtering by path prefix, error status, staleness, lock state, and
29
+ disabled status. Use for engine health checks and finding stale knowledge.
30
+ Each meta entry includes `phaseState` (`{ architect, builder, critic }`)
31
+ showing the per-phase state.
24
32
 
25
33
  **Parameters:**
26
34
  - `pathPrefix` (optional): Filter by path prefix (e.g. "github/")
27
- - `filter` (optional): Structured filter (`{ hasError: true }`, `{ staleHours: 24 }`)
35
+ - `filter` (optional): Structured filter (`{ hasError: true }`, `{ staleHours: 24 }`, `{ disabled: true }`)
28
36
  - `fields` (optional): Property projection array
29
37
 
30
38
  ### meta_detail
31
- Full detail for a single meta, with optional archive history.
39
+ Full detail for a single meta, with optional archive history. Includes
40
+ `_phaseState` showing the per-phase state machine status.
32
41
 
33
42
  **Parameters:**
34
43
  - `path` (required): `.meta/` or owner directory path
@@ -36,20 +45,22 @@ Full detail for a single meta, with optional archive history.
36
45
  - `includeArchive` (optional): false, true, or number (N most recent)
37
46
 
38
47
  ### meta_preview
39
- Dry-run for the next synthesis cycle. Shows scope files, delta files,
40
- architect trigger reasons, steer status, and structure changes without
41
- running any LLM calls. Use before `meta_trigger` to understand what
42
- will happen.
48
+ Dry-run for the next synthesis candidate. Shows scope files, delta files,
49
+ architect trigger reasons, steer status, structure changes, and the
50
+ phase that would execute next — without running any LLM calls. Includes
51
+ `phaseState` and `owedPhase` (the phase that would run). Use before
52
+ `meta_trigger` to understand what will happen.
43
53
 
44
54
  **Parameters:**
45
55
  - `path` (optional): Specific `.meta/` or owner directory path. If omitted,
46
56
  previews the stalest candidate.
47
57
 
48
58
  ### meta_trigger
49
- Enqueue a synthesis cycle for a specific meta or the next-stalest candidate.
59
+ Enqueue a synthesis for a specific meta or the next-stalest candidate.
50
60
  The synthesis runs asynchronously in the service queue; the tool returns
51
- immediately with the queue position. The full cycle (architect builder
52
- critic) runs in the background.
61
+ immediately with the queue position. Only one phase runs per tick (the
62
+ owed phase). Includes `owedPhase` in the response showing which phase
63
+ will execute.
53
64
 
54
65
  **Parameters:**
55
66
  - `path` (optional): Specific `.meta/` or owner directory path. If omitted,
@@ -86,16 +97,30 @@ filtering to extract specific settings. Sensitive fields (e.g.
86
97
  - `path` (optional): JSONPath expression (e.g. `$.schedule`). If omitted,
87
98
  returns the full sanitized config.
88
99
 
100
+ ### meta_update
101
+ Update user-settable reserved properties on a meta entity. Use this to
102
+ toggle `_disabled`, change `_steer`, adjust `_emphasis` or `_depth`, or
103
+ modify `_crossRefs` — without editing `meta.json` directly on the filesystem.
104
+
105
+ **Parameters:**
106
+ - `path` (required): `.meta/` or owner directory path.
107
+ - `updates` (required): Object with properties to set. Supported:
108
+ `_steer`, `_emphasis`, `_depth`, `_crossRefs`, `_disabled`.
109
+ Set a value to `null` to remove the property.
110
+
89
111
  ### meta_queue
90
112
  Queue management: list pending items, clear the queue, or abort current
91
- synthesis. The synthesis queue is single-threaded; use this tool to inspect
92
- what's running, clear queued work, or abort a stuck synthesis.
113
+ synthesis. The queue has three layers: `current` (the running phase),
114
+ `overrides` (explicitly triggered entries), and `automatic` (scheduler-
115
+ computed candidates). The `pending` and `state` fields provide legacy
116
+ compatibility.
93
117
 
94
118
  **Parameters:**
95
119
  - `action` (required): One of `list`, `clear`, `abort`.
96
- - `list`: Show current queue state (current synthesis, pending items).
97
- - `clear`: Remove all pending queue items.
98
- - `abort`: Stop the currently running synthesis and release its lock.
120
+ - `list`: Show current queue state (current with phase, overrides,
121
+ automatic candidates, pending items).
122
+ - `clear`: Remove all override queue entries.
123
+ - `abort`: Stop the currently running phase and release its lock.
99
124
 
100
125
  ## When to Use
101
126
 
@@ -113,6 +138,9 @@ what's running, clear queued work, or abort a stuck synthesis.
113
138
  - **Checking queue state:** `meta_queue` with action `list`
114
139
  - **Clearing queued work:** `meta_queue` with action `clear`
115
140
  - **Aborting stuck synthesis:** `meta_queue` with action `abort`
141
+ - **Disabling a meta:** `meta_update` with path and `updates: { _disabled: true }`
142
+ - **Re-enabling a meta:** `meta_update` with path and `updates: { _disabled: null }`
143
+ - **Changing steer via API:** `meta_update` with path and `updates: { _steer: "new focus" }`
116
144
  - **Reading synthesis output:** Use `watcher_search` filtered by the properties
117
145
  configured in `metaProperty` (e.g. `{ "domains": ["meta"] }` in production).
118
146
  The default properties are `{ _meta: "current" }` for live metas and
@@ -131,6 +159,10 @@ what's running, clear queued work, or abort a stuck synthesis.
131
159
  - **Staleness:** Time since last synthesis. Deeper metas (leaves) update more
132
160
  often than rollup metas (parents). Cross-ref freshness does NOT affect
133
161
  the referencing meta's staleness — each meta synthesizes independently.
162
+ - **Disabled (`_disabled`):** Set `_disabled: true` on a meta to exclude it
163
+ from automatic staleness scheduling. The scheduler and auto-select both
164
+ skip disabled metas. Manual triggers (`meta_trigger` with explicit path)
165
+ still work. Use `meta_update` to toggle the flag.
134
166
  - **Three steps:** Architect crafts the task brief, Builder produces content,
135
167
  Critic evaluates quality. The feedback loop self-improves over cycles.
136
168
  - **Archives:** Each cycle creates a timestamped snapshot in `.meta/archive/`.
@@ -140,6 +172,17 @@ what's running, clear queued work, or abort a stuck synthesis.
140
172
  (e.g. phased analysis, incremental refinement). On builder timeout, the
141
173
  engine attempts to recover partial output — if `_state` advanced, it saves
142
174
  the new state without overwriting existing content.
175
+ - **Phase-state machine (`_phaseState`):** Each meta tracks its three phases
176
+ independently: `{ architect: <state>, builder: <state>, critic: <state> }`.
177
+ States are `fresh`, `stale`, `pending`, `running`, or `failed`. The
178
+ scheduler picks the single highest-priority owed phase across all metas
179
+ each tick (critic > builder > architect, with staleness tiebreaking).
180
+ Failed phases are automatically retried on the next tick (promoted from
181
+ `failed` → `pending`). Only the failed phase reruns — upstream/downstream
182
+ phases are untouched (surgical retries). A full cycle completes only when
183
+ all three phases are `fresh`, at which point the archive snapshot is taken
184
+ and `_synthesisCount` increments. Legacy metas without `_phaseState` have
185
+ their state derived automatically from existing fields on first load.
143
186
 
144
187
  ## Configuration
145
188
 
@@ -498,9 +541,10 @@ The service exposes these endpoints (default port 1938):
498
541
 
499
542
  | Method | Path | Description |
500
543
  |--------|------|-------------|
501
- | GET | `/status` | Service health, queue state, dependency checks |
544
+ | GET | `/status` | Service health, queue state, dependency checks, phase-state summary |
502
545
  | GET | `/metas` | List metas with filtering and field projection |
503
546
  | GET | `/metas/:path` | Single meta detail with optional archive |
547
+ | PATCH | `/metas/:path` | Update user-settable reserved properties |
504
548
  | GET | `/preview` | Dry-run next synthesis candidate |
505
549
  | POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
506
550
  | POST | `/synthesize/abort` | Abort the currently running synthesis |
@@ -508,8 +552,8 @@ The service exposes these endpoints (default port 1938):
508
552
  | POST | `/unlock` | Remove `.lock` file from a meta entity |
509
553
  | GET | `/config` | Query sanitized config with optional JSONPath (`?path=$.schedule`) |
510
554
  | POST | `/config/apply` | Apply a config patch (merge or replace) |
511
- | GET | `/queue` | Current queue state (current, pending, stats) |
512
- | POST | `/queue/clear` | Remove all pending queue items |
555
+ | GET | `/queue` | Queue state: current (with phase), overrides, automatic, pending |
556
+ | POST | `/queue/clear` | Remove all override queue entries |
513
557
 
514
558
  All endpoints return JSON. The OpenClaw plugin tools are thin wrappers
515
559
  around these endpoints.
@@ -534,15 +578,22 @@ The `start` command uses `--config`/`-c` instead (port is read from the config f
534
578
  Recommended periodic checks:
535
579
  - **Errors:** `meta_list` with `filter: { hasError: true }` — investigate
536
580
  and retry with `meta_trigger`
581
+ - **Failed phases:** The TOOLS.md injection shows a "Failed:" alert listing
582
+ metas with failed phases. Failed phases auto-retry on the next scheduler
583
+ tick. Use `meta_detail` to inspect the `_phaseState` and `_error` fields.
537
584
  - **Stuck locks:** `meta_list` with `filter: { locked: true }` — locks
538
585
  older than 30 minutes indicate a crashed synthesis; use `jeeves-meta unlock`
539
586
  - **Stale knowledge:** `meta_list` with `filter: { staleHours: 48 }` — check
540
587
  if the scheduler is running and the watcher is up
588
+ - **Phase health:** `/status` includes `phaseStateSummary` with aggregate
589
+ counts per phase (`fresh`, `stale`, `pending`, `running`, `failed`) and
590
+ `nextPhase` showing the next candidate.
541
591
  - **Service health:** `/status` endpoint (via `meta_list` summary or direct
542
592
  HTTP) includes dependency status for watcher and gateway
543
593
 
544
594
  The TOOLS.md injection surfaces the most critical stats (entity count, errors,
545
- stalest entity) in the agent's system prompt automatically.
595
+ stalest entity, phase summary, failed-phase alerts, next-phase indicator) in
596
+ the agent's system prompt automatically.
546
597
 
547
598
  ## Troubleshooting
548
599
 
@@ -603,18 +654,22 @@ progressive work is not lost on timeout — only the content update is skipped.
603
654
  3. Check if the LLM provider is slow or rate-limited
604
655
  4. Check scope size: large scopes with many files take longer
605
656
 
606
- ### LLM errors in synthesis steps
657
+ ### LLM errors in synthesis phases
607
658
 
608
- **Symptom:** `meta_detail` shows `_error` field with step/code/message
659
+ **Symptom:** `meta_detail` shows `_error` field with step/code/message, and
660
+ `_phaseState` shows `failed` for one or more phases.
609
661
  **Cause:** Subprocess failed (API error, malformed output, rate limit)
610
662
  **Fix:**
611
663
  1. Check error details: `meta_detail <path>` — `_error.step` tells you
612
- which step failed
613
- 2. Architect failure with existing `_builder`: engine reuses cached brief
664
+ which phase failed; `_phaseState` shows the exact state of each phase
665
+ 2. Failed phases are **automatically retried** on the next scheduler tick
666
+ (promoted from `failed` → `pending`). Only the failed phase reruns —
667
+ other phases are untouched (surgical retry).
668
+ 3. Architect failure with existing `_builder`: engine reuses cached brief
614
669
  (self-healing)
615
- 3. Architect failure without `_builder` (first run): retry with `meta_trigger`
616
- 4. Builder failure: meta stays stale, retried next cycle automatically
617
- 5. Critic failure: content saved without feedback, not critical
670
+ 4. Architect failure without `_builder` (first run): retry with `meta_trigger`
671
+ 5. Builder failure: meta stays stale, retried next tick automatically
672
+ 6. Critic failure: content saved without feedback, not critical
618
673
 
619
674
  ### Discovery returns wrong/stale results
620
675
 
@@ -630,8 +685,9 @@ not yet indexed new files
630
685
 
631
686
  ## Gotchas
632
687
 
633
- - `meta_trigger` runs a full LLM cycle (3 subprocess calls). It can take
634
- several minutes.
688
+ - `meta_trigger` enqueues a single phase (not all three). A full cycle
689
+ requires three separate ticks (one per phase). Use `meta_detail` to
690
+ check `_phaseState` for progress.
635
691
  - A locked meta (another synthesis in progress) will be skipped silently.
636
692
  - First-run quality is lower — the feedback loop needs 2-3 cycles to calibrate.
637
693
  - Changing `metaProperty` requires both a meta service restart AND a watcher reindex.
@@ -642,9 +698,12 @@ not yet indexed new files
642
698
  - All prompts are compiled as Handlebars templates. Avoid using `{{` in prompt
643
699
  overrides unless you intend template variable resolution. Escape with `\{{`
644
700
  for literal double-braces.
645
- - The synthesis queue is single-threaded: one synthesis at a time. HTTP-triggered
646
- syntheses get priority over scheduler-triggered ones.
701
+ - The synthesis queue is single-threaded with three layers: `current` (the
702
+ running phase), `overrides` (explicitly triggered entries, highest priority),
703
+ and `automatic` (scheduler-computed candidates). Override entries are
704
+ processed before automatic candidates.
647
705
  - The scheduler uses adaptive backoff: if no stale candidates are found, it
648
- doubles the skip interval (max 4×). Backoff resets after a successful synthesis.
706
+ doubles the skip interval (max 4×). Backoff resets after any successful
707
+ phase execution (not just full-cycle completion).
649
708
  - All CLI commands except `start` require the service to be running (they call
650
709
  the HTTP API).
@@ -2,7 +2,7 @@
2
2
  "id": "jeeves-meta-openclaw",
3
3
  "name": "Jeeves Meta",
4
4
  "description": "Knowledge synthesis tools — trigger synthesis, view status, manage entities.",
5
- "version": "0.10.7",
5
+ "version": "0.12.0",
6
6
  "skills": [
7
7
  "dist/skills/jeeves-meta"
8
8
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@karmaniverous/jeeves-meta-openclaw",
3
- "version": "0.10.7",
3
+ "version": "0.12.0",
4
4
  "author": "Jason Williscroft",
5
5
  "description": "OpenClaw plugin for jeeves-meta — synthesis tools and virtual rule registration",
6
6
  "license": "BSD-3-Clause",