lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/CLAUDE.md
Rongsong Shen 5b05d51b7a
docs(steering): resource decision and question log (PR-1..3 proposals, R/P/N items) 
Persistent log of the resource-design discussion: the user's proposals
(generic supply map incl. provisioned supply; a resource provider proxy
between the controller and upstream providers; datasets in the map with
staging as data provisioning) with analysis, the user's 2026-10-11 input
(duration/decay must-have but future; RBAC in the apiserver, discuss later;
OCI containers via application profiles; CSI compatibility preferred;
GPU/topology scheduler-first and extensible), the open R1-R9/P1-P9 items
and new questions N1-N4, C3. resource-model.md, the provisioner research,
roadmap and CLAUDE.md point at it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-12 04:00:47 +00:00

8.8 KiB
Raw Blame History

OpenWolf

This project uses OpenWolf for context management. The always-on rules live in .claude/rules/openwolf.md; the hooks handle bookkeeping (anatomy index, memory log, read tracking) automatically.

For the full operating protocol (session handoff, memory discipline, bug logging), load the openwolf skill, or read .wolf/OPENWOLF.md. Regenerate the session handoff with /handoff.

XCE Cluster Management System

Project Overview

XCE is an HPC cluster management system — Go API/CLI tier fronting C daemons (controller, worker, scheduler). Full context in .kiro/steering/product.md.

Engineering Guide

For details on any topic below, read the corresponding steering file in .kiro/steering/. CLAUDE.md provides pointers, not duplicates.

Topic Steering File
Project purpose, HA phases, design decisions product.md
Technology stack, build systems, key decisions tech.md
Directory layout, naming conventions, test org structure.md
Build commands, Nix flake, deploy, AppImage build-deployment.md
REST handler pattern, daemon opcodes, Cap'n Proto api-standards.md
HA protocol, async I/O, Raft election, heartbeat ha-async-io.md
TDD rules, C + Go test patterns, coverage targets testing.md
Error handling: Go ReturnError, C errnox, zap logging error-handling.md
RBAC, JWT, auth backends, input validation, secrets security.md
WAL durability, recovery, save/restore field-completeness persistence.md
Real vs. virtual resources, reservation-vs-usage accounting (mem) resource-accounting.md
Resource model: attributes / counters / instances+claims, providers, K8s-LSF mapping, LLM direction resource-model.md
Resource design decisions, proposals and open questions (discussion log) resource-questions.md
Job/app-profile/queue/project ownership and merge rules job-config-layering.md

Key Rules (from steering — summarized for quick reference)

  • TDD mandatory: red → green → refactor; test in testsuite/ before C changes, _test.go before Go changes
  • Async I/O: delaymgr is trigger-only and must never block (no connect(), no file I/O) — it drives heartbeats/election timeouts, so blocking there causes spurious failover. Long/unbounded blocking goes on the slow lane; bounded blocking in vtask handlers is permitted only under an admission reservation (COMMIT_WAIT_RESERVED). xce_request/xce_reply are always non-blocking. See ha-async-io.md
  • Connections are long-lived: closing signals RDHUP failover. Inbound connections are vote-only; outbound carry all state push
  • No fork in multi-threaded processes: controller, scheduler, xcecd and anything that starts libxce threads never call fork/vfork/daemon/system/popen/uv_spawn; start children with posix_spawn() or a systemd unit. A process proven single-threaded (xcecd_worker) may fork, marked /* xce-fork-ok: <why> */. Tests, harness, autoscaler and Go are out of scope; enforced by scripts/check-no-fork.py (meson test + pre-commit). See tech.md "Process Creation"
  • Middleware chain (non-negotiable): WhitelistURL → WhitelistIP → RateLimit → JWT → CORS → RBAC
  • Error pattern: ReturnError(code, msg, nil); return — early return on every error
  • Build: /xce-build [component] — debug + ASAN + tests. Components: all (default), lib, controller, harness, scheduler, worker, apiserver, xcecli, xceadmin. See build-deployment.md for full commands
  • Buglog: each bug is a Markdown record .wolf/bugs/<id>.md written to the standard in .claude/skills/buglog/bug-record.md (Description, Environment incl. OS/libc/toolchain/commit, Reproduction; Root cause, Fix, Verification and fix commits once fixed). Create and change records only through the buglog skill (scripts/buglog.py new | status | note | recur | check | list --open), which enforces the standard (so does the pre-commit hook); .wolf/buglog.json is a generated index, never edit it. The front-matter status is the only source of truth for open/closed (values in .claude/rules/buglog-status.md); after a fix commit run scripts/buglog.py status <id> fixed --commit <sha>
  • Save/restore field-completeness: any persistence mechanism (WAL fact, scheduler snapshot, checkpoint) must capture every field of the entity it claims to persist — a state that "recovers correctly" while silently missing a field it depends on (e.g. job.state correct but job.allocs lost) is a bug, not an acceptable simplification, unless the omission is explicitly documented as a scope decision (see persistence.md's "Snapshot Save/Load Field-Completeness" + APPLY_CLEAN/bug-1678 sections). When adding or extending save/restore logic, verify the field round-trips through BOTH the write side and every read/apply seam, and run /xce-audit-invariants (controller dimension 7 / scheduler dimension 4) rather than assuming a passing test suite already proves it — APPLY_CLEAN-style verdicts check row counts and cursor position, not per-field completeness

Key Files

  • src/tools/xce-build.sh — primary build/test orchestration (Meson-based; see build-deployment.md)
  • src/frontend/apiserver/cmd/main.go — server startup, init sequence
  • src/frontend/apiserver/router/routers.go — all routes and middleware chain
  • src/frontend/apiserver/controllers/rbac_check.go — RBAC loading and enforcement
  • src/frontend/apiserver/config/rbac.yaml — role/permission definitions
  • src/frontend/apiserver/config/auth.yaml — auth provider selection

Subdirectory Guidelines

  • src/frontend/ — See src/frontend/CLAUDE.md
  • src/controller/ — See src/controller/CLAUDE.md
  • src/harness/ — See src/harness/CLAUDE.md
  • src/worker/ — See src/worker/CLAUDE.md
  • src/scheduler/ — See src/scheduler/CLAUDE.md
  • src/lib/ — See src/lib/CLAUDE.md

Agentic SDLC and Spec-Driven Development

Kiro-style Spec-Driven Development on an agentic SDLC

Project Context

Paths

  • Steering: .kiro/steering/
  • Specs: .kiro/specs/

Steering vs Specification

Steering (.kiro/steering/) - Guide AI with project-wide rules and context Specs (.kiro/specs/) - Formalize development process for individual features

Active Specifications

  • Check .kiro/specs/ for active specifications
  • Use /kiro-spec-status [feature-name] to check progress

Development Guidelines

  • Think in English, generate responses in English. All Markdown content written to project files (e.g., requirements.md, design.md, tasks.md, research.md, validation reports) MUST be written in the target language configured for this specification (see spec.json.language).

Minimal Workflow

  • Phase 0 (optional): /kiro-steering, /kiro-steering-custom
  • Phase 1 (Specification):
    • /kiro-spec-init "description" — initialize spec scaffold
    • /kiro-spec-quick "description" — fast single-pass spec (requirements + design + tasks, no approval gates)
    • /kiro-spec-batch — generate specs for all features in a roadmap in parallel
    • /kiro-spec-requirements {feature}
    • /kiro-validate-gap {feature} (optional: for existing codebase)
    • /kiro-spec-design {feature} [-y]
    • /kiro-validate-design {feature} (optional: design review)
    • /kiro-spec-tasks {feature} [-y]
  • Phase 2 (Implementation): /kiro-impl {feature} [tasks]
    • /kiro-validate-impl {feature} (optional: after implementation)
    • /kiro-verify-completion {feature} — validate all acceptance criteria are met
  • Debugging: /kiro-debug {feature} — systematic debugging with spec context
  • Code review: /kiro-review — review implementation against spec requirements
  • Progress check: /kiro-spec-status {feature} (use anytime)

Development Rules

  • 3-phase approval workflow: Requirements → Design → Tasks → Implementation
  • Human review required each phase; use -y only for intentional fast-track
  • Use /kiro-spec-quick for small, well-understood features; full workflow for anything touching HA/persistence/RBAC
  • Keep steering current and verify alignment with /kiro-spec-status
  • Follow the user's instructions precisely, and within that scope act autonomously: gather the necessary context and complete the requested work end-to-end in this run, asking questions only when essential information is missing or the instructions are critically ambiguous.

Steering Configuration

  • Load entire .kiro/steering/ as project memory — all .md files are authoritative
  • Core: product.md, tech.md, structure.md
  • Custom: testing.md, error-handling.md, security.md, ha-async-io.md, api-standards.md, build-deployment.md, config-design.md, persistence.md, resource-accounting.md, resource-model.md, resource-questions.md, job-config-layering.md, roadmap.md
  • Add new custom files via /kiro-steering-custom; sync existing via /kiro-steering