feat(buglog): one Markdown record per bug, checked against a record standard

The buglog was one 27K-line JSON file whose fields covered only symptom,
root cause and fix, as free text: 2% of entries named the code version a
bug was found on, 12% the build profile, 36% a way to reproduce, and 58% of
the file was OpenWolf hook auto-detections ("Missing guard clause",
"Function not marked async" on .md files).

- .claude/skills/buglog/bug-record.md: the record standard. Eight
  sections (Summary as the title, Description, Environment, Reproduction;
  Root cause, Fix, Verification, References once fixed), each with the
  content it must contain -- e.g. Environment needs the OS, the libc the
  failing binary loads (from its ELF interpreter: glibc 2.42 in the nix
  shell vs 2.40 on the host), toolchain, build profile and commit.
- .wolf/bugs/<id>.md: 500 records migrated from buglog.json; every field
  verified to round-trip. They carry legacy: true and an explicit "not
  recorded" where the old log had no such field; component derived from
  file paths, severity from keywords (else unknown), fix_commits from
  hashes in status_note/fix that git resolves (91 of 463 fixed).
- .wolf/buglog-archive.json: the 710 hook auto-detections, verbatim.
- .wolf/buglog.json is now an index generated from the records, keeping
  the fields OpenWolf's hooks and `openwolf bug search` read.
- scripts/buglog.py rewritten: new (template + Environment collected from
  the machine and --binary), check, status (refuses a status the record
  doesn't support; fixed needs Root cause, Fix, Verification and
  --commit hashes git resolves), note, recur, set, show, list, triage,
  env, index. 29 unittest cases in scripts/tests/test_buglog.py.
- scripts/git-hooks/pre-commit runs `check --staged`: incomplete staged
  records, a legacy record hand-changed to fixed without the fix-time
  sections, a new record claiming legacy: true, or a stale index refuse
  the commit.
- scripts/gitea-sync.py reads the records: issue body = the record's
  sections plus linked fix commits (origin remote, GITEA_COMMIT_REPO to
  override), and a body hash so an issue's text is refreshed when the
  record changes.
- bug-1866 rewritten to the full standard as the worked example.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

2026-09-28 03:40:11 +00:00

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`

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. 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, roadmap.md
Add new custom files via /kiro-steering-custom; sync existing via /kiro-steering

8 KiB Raw Blame History