pdurlej/platform
1
1
Fork 0
Code Issues 44 Pull requests 1 Projects Releases Packages Wiki Activity Actions

WIP: docs(specs): OpenClaw Scheduler Observability — Spec Kit + inventory code #568

Closed
ollama wants to merge 2 commits from ollama/dziadek-openclaw-scheduler-spec into main
pull from: ollama/dziadek-openclaw-scheduler-spec
merge into: pdurlej:main
Conversation 3 Commits 2 Files changed 9 +767
ollama commented 2026-05-28 13:07:38 +02:00
Collaborator
Copy link

WIP — OpenClaw Scheduler Observability Spec Kit

Cherry-pick of claude's original pre-impl skeleton (2026-05-17, from branch claude/feat-openclaw-scheduler-observability, never merged).

Original author: claude
Refreshed by: dziadek (DeepSeek-v4-Pro / ollama)
Source issue: #135 (Iskra-authored, OPEN, 5 comments, milestone 08)

The problem

Iskra discovered (2026-05-09) that OpenClaw's scheduler on VPS1000 has split brain:

  • Active cron store: missing/empty
  • Legacy cron store: contains old jobs
  • systemd timers: own some automations
  • openclaw cron list: crashes
  • A checkpoint exists in the promise ledger with no backing scheduled job

Operator won't upgrade OpenClaw until this is understood.

What this ships (9 files, ~767 LOC)

Spec Kit (docs/specs/openclaw-scheduler-observability-v0/, 6 files):

  • 00-constitution — 7 principles (ledger↔jobs consistency, checklist-gated upgrade, snapshot-before-mutation, read-only first)
  • 01-specify — 8 FRs (inventory, drift, repair, snapshot, preflight, gate, audit, ownership)
  • 02-plan — 3 slices (a/b/c), M1-M4
  • 03-tasks — ~1600 LOC v0 estimate
  • 04-implement-notes — 10 pre-impl decisions
  • README

Code skeleton (scripts/openclaw_scheduler/):

  • _types.py — JobRecord, DriftEntry, DriftReport, SchedulerStore enum
  • inventory.py — read_active_cron, read_legacy_cron, read_systemd_timers, full_inventory stubs

Key design decisions

  • Read cron stores directly (NOT via openclaw cron list which crashes)
  • tar+SHA-256 snapshot before any mutation
  • Ownership registry: sacred-adjacent
  • JSONL audit trail
  • Dry-run as default; operator-gated mutations
  • Cross-store conflict → operator decision, not silent repair

What this PR does NOT

  • Does NOT implement actual inventory/repair scripts (stubs only)
  • Does NOT perform any OpenClaw upgrade
  • Does NOT modify cron stores or systemd timers

Role: deep-reviewer
Refs: #135, Iskra evidence 2026-05-09

## WIP — OpenClaw Scheduler Observability Spec Kit Cherry-pick of claude's original pre-impl skeleton (2026-05-17, from branch `claude/feat-openclaw-scheduler-observability`, never merged). **Original author:** claude **Refreshed by:** dziadek (DeepSeek-v4-Pro / ollama) **Source issue:** #135 (Iskra-authored, OPEN, 5 comments, milestone 08) ## The problem Iskra discovered (2026-05-09) that OpenClaw's scheduler on VPS1000 has split brain: - Active cron store: missing/empty - Legacy cron store: contains old jobs - systemd timers: own some automations - `openclaw cron list`: crashes - A checkpoint exists in the promise ledger with no backing scheduled job Operator won't upgrade OpenClaw until this is understood. ## What this ships (9 files, ~767 LOC) **Spec Kit** (`docs/specs/openclaw-scheduler-observability-v0/`, 6 files): - 00-constitution — 7 principles (ledger↔jobs consistency, checklist-gated upgrade, snapshot-before-mutation, read-only first) - 01-specify — 8 FRs (inventory, drift, repair, snapshot, preflight, gate, audit, ownership) - 02-plan — 3 slices (a/b/c), M1-M4 - 03-tasks — ~1600 LOC v0 estimate - 04-implement-notes — 10 pre-impl decisions - README **Code skeleton** (`scripts/openclaw_scheduler/`): - `_types.py` — JobRecord, DriftEntry, DriftReport, SchedulerStore enum - `inventory.py` — read_active_cron, read_legacy_cron, read_systemd_timers, full_inventory stubs ## Key design decisions - Read cron stores directly (NOT via `openclaw cron list` which crashes) - tar+SHA-256 snapshot before any mutation - Ownership registry: sacred-adjacent - JSONL audit trail - Dry-run as default; operator-gated mutations - Cross-store conflict → operator decision, not silent repair ## What this PR does NOT - Does NOT implement actual inventory/repair scripts (stubs only) - Does NOT perform any OpenClaw upgrade - Does NOT modify cron stores or systemd timers **Role:** deep-reviewer **Refs:** #135, Iskra evidence 2026-05-09
Pre-impl skeleton + Spec Kit for issue #135 OpenClaw Scheduler Observability.

Status: draft — for review, NOT for merge. Pattern: hybrid GitHub Spec Kit +
code skeleton (siblings: PR #323 Agent Access Plane, PR #324 Agent Wake Bus;
pdurlej/iskra-openclaw PR #276/#278/#279/#281).

Source: issue #135 (Iskra-authored, 2026-05-09 evidence:
forgejo-self-audit-20260504 checkpoint exists without backing scheduled job).

What's in here (~900 LOC):

Spec Kit (6 markdowns, ~800 lines):
- 00-constitution.md — 7 principles (scheduler ownership explicit, ledger ↔
  jobs consistency, checklist-gated upgrade, snapshot before mutation,
  read-only first, openclaw cron list MUST NOT fail silently, cross-store
  reconciliation is operator-decision), 8 anti-patterns, boundary.
- 01-specify.md — 8 FRs (inventory, drift, repair, snapshot, preflight, gate,
  audit, ownership), 6 NFRs, 5 open questions, 6 falsifiable success criteria.
- 02-plan.md — 3 slices (a/b/c), M1-M4, 6 risks, rollback per slice,
  composability with OpenClaw upgrade pipeline + Wake Bus drift alerts.
- 03-tasks.md — atomic tasks, ~1600 LOC v0 estimate, codex execution notes.
- 04-implement-notes.md — 10 pre-impl decisions (read jobs.json directly NOT
  via `openclaw cron list`; tar+SHA-256 snapshot; ownership registry sacred-
  adjacent; JSONL audit; run as openclaw user; dry-run default; 5/30d
  retention; schema drift = warn; systemd ownership canonical for system jobs;
  cross-store conflict = operator-decision).
- README.md — index.

Code skeleton (py_compile clean):
- scripts/openclaw_scheduler/_types.py — JobRecord, DriftEntry, DriftReport,
  SchedulerStore (4-value enum: active_cron, legacy_cron, systemd_timers,
  promise_ledger), DriftSeverity, JobStatus
- scripts/openclaw_scheduler/inventory.py — read_active_cron, read_legacy_cron,
  read_systemd_timers, read_promise_ledger, full_inventory, main stubs with
  TODO(codex Slice a) markers + canonical paths

Cross-references:
- Issue #135 (Iskra-authored parent + 2026-05-09 evidence)
- pdurlej/iskra-openclaw runtime (sacred path boundary; v0 expects no schema
  changes during platform v0 development)
- PR #323 (Agent Access Plane) — same audit JSONL pattern
- PR #324 (Wake Bus) — could emit alerts on detected drift
- ADR-0004 Iskra telemetry boundary
- ADR-0018 — no silent repair, operator-gated mutations
- Pan Herbatka day-1 checklist § 5 sacred paths

Tier: this PR Trivial (draft scaffold). Future slice PRs: Lite (a/b), Full (c)
per ADR-0007 — Slice (c) repair scripts are class/security-sensitive.

Refs #135
docs(specs): add refresh note to openclaw-scheduler README (dziadek)
Some checks failed
canary-required / collect-diff (pull_request) Successful in 4s
Details
patchwarden-client-dry-run / collect-diff (pull_request) Successful in 4s
Details
canary-required / canary (pull_request) Has been skipped
Details
patchwarden-client-dry-run / dry-run (pull_request) Successful in 22s
Details
base-is-main / guard (pull_request) Successful in 1s
Details
patchwarden-pr-sanity / collect-diff (pull_request) Successful in 5s
Details
patchwarden-pr-sanity / sanity (pull_request) Failing after 6m0s
Details
fbc231fb0d 
Verified 2026-05-28: issue #135 still OPEN, milestone 08.
Original: claude (2026-05-17)
codex changed title from docs(specs): OpenClaw Scheduler Observability — Spec Kit + inventory code (WIP) to WIP: docs(specs): OpenClaw Scheduler Observability — Spec Kit + inventory code 2026-05-28 14:56:45 +02:00
codex commented 2026-05-28 22:48:51 +02:00
Collaborator
Copy link

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current main, rerun validation, and split/merge only if it directly supports the current milestone. No OpenClaw runtime mutation should happen from this PR.

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current `main`, rerun validation, and split/merge only if it directly supports the current milestone. No OpenClaw runtime mutation should happen from this PR.
codex commented 2026-05-30 08:59:18 +02:00
Collaborator
Copy link

Codex note: this WIP PR is valuable but structurally stale against current main.

I inspected the diff and it now carries large accidental reverse-diff churn unrelated to OpenClaw scheduler observability. I opened a clean replacement PR that preserves only the intended 9 files from this branch:

Recommendation: keep this PR open only until #631 merges, then close this as superseded so the archival content is preserved without merging stale branch drift.

Secret output: none.

Codex note: this WIP PR is valuable but structurally stale against current `main`. I inspected the diff and it now carries large accidental reverse-diff churn unrelated to OpenClaw scheduler observability. I opened a clean replacement PR that preserves only the intended 9 files from this branch: - replacement: #631 - parent issue: #135 Recommendation: keep this PR open only until #631 merges, then close this as superseded so the archival content is preserved without merging stale branch drift. Secret output: none.
pdurlej referenced this pull request from a commit 2026-05-30 09:13:51 +02:00
Merge pull request #631
codex commented 2026-05-30 09:14:58 +02:00
Collaborator
Copy link

Superseded by #631, which rescued the intended OpenClaw scheduler observability Spec Kit from a fresh main branch and merged it without the stale broad diff from this WIP branch.

Leaving this PR closed as archival context only. No runtime changes were taken from this branch.

Superseded by #631, which rescued the intended OpenClaw scheduler observability Spec Kit from a fresh `main` branch and merged it without the stale broad diff from this WIP branch. Leaving this PR closed as archival context only. No runtime changes were taken from this branch.
codex closed this pull request 2026-05-30 09:14:58 +02:00
Some checks failed
canary-required / collect-diff (pull_request) Successful in 4s
Details
patchwarden-client-dry-run / collect-diff (pull_request) Successful in 4s
Details
canary-required / canary (pull_request) Has been skipped
Details
patchwarden-client-dry-run / dry-run (pull_request) Successful in 22s
Details
base-is-main / guard (pull_request) Successful in 1s
Required
Details
patchwarden-pr-sanity / collect-diff (pull_request) Successful in 5s
Details
patchwarden-pr-sanity / sanity (pull_request) Failing after 6m0s
Required
Details

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
W6d-automerge-calibration

   
agent/claude-code
Vistula actor: Claude Code.

  
agent/codex
Vistula actor: Codex.

  
agent/hermes
Vistula actor: Hermes Upstream.

  
agent/iskra
Vistula actor: Iskra.

  
agent/ollama
Vistula actor: Ollama or compatible model.

  
agent/patchwarden
Vistula actor: Patchwarden.

  
automerge-candidate
Candidate for narrow W6d autonomous merge readiness pilot

  
class/security-sensitive
Security-sensitive class of service: smallest coherent PRs and full canary

  
cutover-gate
blocks production declare / final RS2000 replacement

  
dependency/blocked
Vistula dependency state: blocked.

  
dependency/blocks-others
Vistula dependency state: blocks other work.

  
dependency/cross-repo
Vistula dependency scope: cross-repository.

  
dependency/needs-confirmation
Vistula dependency state: needs confirmation.

  
domain:agents
Agent identity, delegation, subagents, routing, or workflows.

  
domain:ci
CI, checks, Actions, runners, or release automation.

  
domain:docs
Documentation, packets, practices, or source-of-truth text.

  
domain:forgejo
Forgejo issues, PRs, labels, repo settings, or identity.

  
domain:infra
Infrastructure, storage, backup, DNS, network, or host substrate.

  
domain:memory
Memory, recall, write gates, salience, or Honcho-adjacent behavior.

  
domain:runtime
Runtime services, deploys, daemons, timers, or live behavior.

  
domain:signal
Signal UX, delivery, context, or outbound behavior.

  
domain:ux
Product UX, operator experience, or conversation ergonomics.

  
flow/architecture
Vistula lifecycle: architecture phase in progress.

  
flow/blocked
Vistula lifecycle: blocked on dependency or decision.

  
flow/deployed
Vistula lifecycle: deployed to runtime where applicable.

  
flow/done
Vistula lifecycle: work merged or otherwise done.

  
flow/implementation
Vistula lifecycle: implementation phase in progress.

  
flow/intake
Vistula lifecycle: incoming signal not refined yet.

  
flow/maintained
Vistula lifecycle: maintained/steady state.

  
flow/observed
Vistula lifecycle: observed after delivery.

  
flow/ready
Vistula lifecycle: ready for architecture or implementation.

  
flow/refining
Vistula lifecycle: Hermes/spec refinement in progress.

  
flow/retired
Vistula lifecycle: retired or intentionally closed.

  
flow/review
Vistula lifecycle: review phase in progress.

  
iterating
Orchestrator/Codex actively amending in response to review — operator can ignore until resolved

  
judge/codex-candidate
Candidate for Codex implementation.

  
judge/hermes-candidate
Candidate for Hermes discovery/research.

  
judge/low-confidence
Judgment confidence is low.

  
judge/needs-refinement
Needs clearer evidence or scope.

  
judge/operator-needed
Needs Piotr decision or input.

  
judge/p0
Urgent, operator attention or unblock now.

  
judge/p1
High value, schedule soon.

  
judge/p2
Useful, normal queue.

  
judge/p3
Low priority, keep but do not chase.

  
judge/park
Parked from current attention.

  
judge/patchwarden-candidate
Needs Patchwarden merge-safety attention.

  
judge/stale-priority
Existing priority judgment appears stale.

  
kind/adr
Vistula work kind: architecture decision record.

  
kind/bug
Vistula work kind: bug fix.

  
kind/chore
Vistula work kind: chore.

  
kind/feature
Vistula work kind: feature.

  
kind/infra
Vistula work kind: infrastructure.

  
kind/ops
Vistula work kind: operations.

  
kind/refactor
Vistula work kind: refactor.

  
kind/research
Vistula work kind: research/discovery.

  
large-impact
Per charter §3 review-by-impact: large impact (≥300 LOC OR new module OR identity/secret change OR architectural pivot) — Oracle pre-review recommended

  
merge/auto
Vistula merge mode: automated merge.

  
merge/manual
Vistula merge mode: manual merge.

  
merge/manual-dependency-conflict
Manual merge reason: dependency conflict.

  
merge/manual-failing-tests
Manual merge reason: failing tests.

  
merge/manual-merge-conflict
Manual merge reason: merge conflict.

  
merge/manual-missing-review
Manual merge reason: missing review.

  
merge/manual-operator-preference
Manual merge reason: operator preference.

  
merge/manual-red-zone
Manual merge reason: red-zone risk.

  
merge/manual-security-sensitive
Manual merge reason: security-sensitive work.

  
merge/manual-unclear-scope
Manual merge reason: unclear scope.

  
merge/manual-unknown
Manual merge reason: unknown.

  
meta
meta-decomposition issue; first agent decomposes into atomic children

  
mode:operator-only
Apply step requires explicit operator approval.

  
mode:patchwarden-iskra-approved
Work eligible for Patchwarden/Iskra approval inside repo policy.

  
mode:safe-auto
Low-risk work eligible for lightweight autonomous handling.

  
needs-operator-decision
PR is blocked on operator yes/no decision — fresh-Claude/Codex won't make this call alone

  
needs-triage
decomposing agent has open questions / unknowns

  
not-ready
reviewed but blocked on a precondition

  
observed/erroring
Vistula observation: erroring.

  
observed/needs-followup
Vistula observation: needs follow-up.

  
observed/pending
Vistula observation: pending.

  
observed/retire-candidate
Vistula observation: retire candidate.

  
observed/unused
Vistula observation: unused.

  
observed/used
Vistula observation: used.

  
operator-emotional
operator-emotional importance (Iskra memory etc.)

  
owner-attention
owner must decide; blocks default path

  
phase/02
Phase 02 cataloging

  
phase/03
Phase 03 control plane (platformctl)

  
priority:p0
Immediate safety, uptime, data, or operator-blocking issue.

  
priority:p1
Important active work; should be pulled soon.

  
priority:p2
Useful normal-priority work.

  
priority:p3
Opportunistic cleanup, research, or backlog work.

  
proposed
auto-generated by meta-decomposition; awaiting human review

  
ready-for-agent
reviewed and pickable; agents may claim per cookbook

  
ready-for-operator
PR is ready for operator review/merge — orchestrator finished its part

  
recovery
disaster recovery / restore semantics relevant

  
review:claude-reviewed
Reviewed by Claude-family agent.

  
review:codex-reviewed
Reviewed by Codex-family agent.

  
review:dziadek-reviewed
Reviewed by Dziadek pinch-point reviewer.

  
review:needs-human
Needs human review before merge or apply.

  
risk/exposure
incorrectly public/private/tailnet/auth/routed

  
risk/process
workflow/review/orchestration may produce bad outcomes

  
risk/product
work may have lost owner/user value

  
risk/runtime
platform may not run, recover, validate, behave reproducibly

  
safety:external-write
May write to external systems, users, rooms, repos, or services.

  
safety:no-prod-mutation
Must not mutate production or live external state.

  
safety:prod-impact
May affect production/runtime behavior.

  
safety:secret-touch
Touches secrets, credentials, auth, or secret-adjacent config.

  
size/large
Vistula size: large.

  
size/medium
Vistula size: medium.

  
size/small
Vistula size: small.

  
size/tiny
Vistula size: tiny.

  
size/unknown
Vistula size: not classified yet.

  
source/adr
Vistula source: ADR.

  
source/agent-generated
Vistula source: agent generated.

  
source/manual
Vistula source: manual entry.

  
source/operator-chat
Vistula source: operator chat.

  
source/voice-note
Vistula source: voice note.

  
status:blocked
Blocked by missing dependency, evidence, access, or operator decision.

  
status:codex-ready
Ready for a Codex implementation pass.

  
status:merged:pending-evidence
Merged but waiting for live or artifact evidence before closure.

  
status:needs-evidence
Needs proof, logs, tests, or operator-visible evidence.

  
status:operator-needed
Requires explicit operator input before safe progress.

  
status:parked
Intentionally deferred; not active campaign work.

  
tier/full
Full review tier per ADR-0007

  
tier/lite
Lite review tier per ADR-0007

  
tier/stacked
Stacked PR (base != main) escape hatch per ADR-0017. Requires consolidator-PR plan in PR body.

  
tier:0-platform-substrate
Data, secrets, backup, storage, or critical platform substrate.

  
tier:1-iskra-value-layer
Iskra/OpenClaw behavior, memory, runtime, or value-layer work.

  
tier:2-tools-products-modules
Tools, products, modules, experiments, and lower-blast-radius work.

  
type:bug
Incorrect behavior or regression.

  
type:chore
Maintenance, cleanup, metadata, or operational task.

  
type:docs
Documentation-only work.

  
type:feat
New capability or product behavior.

  
type:policy
Governance, protocol, boundary, or decision-contract change.

  
type:research
Investigation, spike, or evidence-gathering task.

No labels
W6d-automerge-calibration
agent/claude-code
agent/codex
agent/hermes
agent/iskra
agent/ollama
agent/patchwarden
automerge-candidate
class/security-sensitive
cutover-gate
dependency/blocked
dependency/blocks-others
dependency/cross-repo
dependency/needs-confirmation
domain:agents
domain:ci
domain:docs
domain:forgejo
domain:infra
domain:memory
domain:runtime
domain:signal
domain:ux
flow/architecture
flow/blocked
flow/deployed
flow/done
flow/implementation
flow/intake
flow/maintained
flow/observed
flow/ready
flow/refining
flow/retired
flow/review
iterating
judge/codex-candidate
judge/hermes-candidate
judge/low-confidence
judge/needs-refinement
judge/operator-needed
judge/p0
judge/p1
judge/p2
judge/p3
judge/park
judge/patchwarden-candidate
judge/stale-priority
kind/adr
kind/bug
kind/chore
kind/feature
kind/infra
kind/ops
kind/refactor
kind/research
large-impact
merge/auto
merge/manual
merge/manual-dependency-conflict
merge/manual-failing-tests
merge/manual-merge-conflict
merge/manual-missing-review
merge/manual-operator-preference
merge/manual-red-zone
merge/manual-security-sensitive
merge/manual-unclear-scope
merge/manual-unknown
meta
mode:operator-only
mode:patchwarden-iskra-approved
mode:safe-auto
needs-operator-decision
needs-triage
not-ready
observed/erroring
observed/needs-followup
observed/pending
observed/retire-candidate
observed/unused
observed/used
operator-emotional
owner-attention
phase/02
phase/03
priority:p0
priority:p1
priority:p2
priority:p3
proposed
ready-for-agent
ready-for-operator
recovery
review:claude-reviewed
review:codex-reviewed
review:dziadek-reviewed
review:needs-human
risk/exposure
risk/process
risk/product
risk/runtime
safety:external-write
safety:no-prod-mutation
safety:prod-impact
safety:secret-touch
size/large
size/medium
size/small
size/tiny
size/unknown
source/adr
source/agent-generated
source/manual
source/operator-chat
source/voice-note
status:blocked
status:codex-ready
status:merged:pending-evidence
status:needs-evidence
status:operator-needed
status:parked
tier/full
tier/lite
tier/stacked
tier:0-platform-substrate
tier:1-iskra-value-layer
tier:2-tools-products-modules
type:bug
type:chore
type:docs
type:feat
type:policy
type:research
Milestone
Clear milestone
No items
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
pdurlej/platform!568
No description provided.