5e2985542f
Two-sided divergence from f01ae353 (2026-08-30): theirs +88 (worker
rejoin-resync reconciliation, terminal-state bug-1737/1738/1739/1764,
scheduler-sim verbosity, hermetic offline build, go mod vendor of Go deps
in apiserver -- 3375 pure-adds), ours +89 (job-finish robustness bug-1509
B1/B3, PEND-reason, worker reconnect resend, apiserver job control).
Conflict resolutions (kept both sides' fixes):
- controller_connector.c checking_connection(): combine theirs
xcecd_resync_is_pending() rejoin deferral gate with ours
resend_job_status() actual-state re-report on rejoin success.
- job.c: keep both unknown-finish registry (ours, bug-1509) and
record_job_finish_fact_at (theirs, bug-1747); keep both
mark_jobs_unknown_core family (ours) and record_job_reconcile_*
(theirs). No double-notify: on_job_finish unchanged, theirs is
resync-path-only.
- scheduler handler.c/test_handlers.c/meson: theirs schedExitJob
exit_code branch (bug-1737) + ours jobDispatchFail success-ack no-op
(bug-1512) + configpush enq_pend_update (bug-1513) both present; both
test suites and REPL/sim targets wired.
- apiserver jobs.go: keep ours normalizeJobInt64/jobArrayIdx superset +
JobIDHuman; drop theirs strict IntOrInt64 early-reject (superseded --
ours tolerates float64/json.Number, no panic path).
- jobs_test.go: keep both regression suites (ours bug-1490, theirs
bug-1742).
- .kiro/specs scheduler-sim-*/worker-rejoin-resync + .wolf/*: keep our
deletions (established convention -- drop Rongsong bookkeeping on merge).
Co-Authored-By: Claude Code <noreply@anthropic.com>
107 lines
7.2 KiB
Markdown
107 lines
7.2 KiB
Markdown
# OpenWolf
|
||
|
||
@.wolf/OPENWOLF.md
|
||
|
||
This project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.
|
||
|
||
|
||
# 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` |
|
||
|
||
## 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
|
||
- **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. See `build-deployment.md` for full commands
|
||
|
||
## Key Files
|
||
- `src/frontend/Makefile` — primary build/test orchestration
|
||
- `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/worker/` — See `src/worker/CLAUDE.md`
|
||
- `src/scheduler/` — See `src/scheduler/CLAUDE.md`
|
||
- `src/lib/` — See `src/lib/CLAUDE.md`
|
||
- `src/frontend/schedulerclient/`, `src/frontend/mcp-server/` — **Phase 0-1 已完成**（Phase 0: 2026-07-26，Phase 1: 2026-08-01）。`schedulerclient` 是独立 Go library，提供读 + 写 Client（6 只读 + 4 写：SubmitJob/CancelJob/HoldJob/ReleaseJob，resty HTTP 实现，33+12 单测）。`mcp-server` 是 MCP stdio 二进制（`github.com/mark3labs/mcp-go@v0.57.0`），通过 `schedulerclient` 调用 `apiserver` REST API，暴露 10 个 MCP Tool（6 只读 + 4 写，写工具含 `dry_run` review 模式 + `general_serial` 作业模板 registry）。Pure Go, `CGO_ENABLED=0`。Phase 1 需 `mcp_operator` RBAC 角色（`config/rbac.yaml`）。总体架构与分阶段计划见 `docs/Scheduler-Agent-设计文档.md`。**集群验证（2026-08-01/02）**：t1 单节点 controller 集群上，读操作（含 OrderMap 解析修复 bug-1491）+ submit 已通过 mcp_operator API key 验证；**作业全部 PEND 不调度**（bug-1494，疑 scheduler→controller join 链路，已补 resources.yaml 但未解决）；hold/release/cancel 因 apiserver control 链路预存 bug（HTTP 500）待修（bug-1490）。
|
||
|
||
# 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`, `roadmap.md`
|
||
- Add new custom files via `/kiro-steering-custom`; sync existing via `/kiro-steering`
|