Build / validate (pull_request) Failing after 1m12s

Details

infra: extract heph.nvim into its own forge repo

The Neovim plugin now lives at eblume/hephaestus.nvim (plugin at the repo
root). Remove heph.nvim/ from the monorepo and the build/test wiring that
referenced it:

- Dagger: drop the test_nvim function + the pinned-Neovim NVIM_VERSION
- build.yaml: drop the `dagger call test-nvim` step
- drop the mise run test-nvim task and .stylua.toml + the stylua prek hook
  (no Lua remains in the monorepo)
- install-heph.md: install via a plain lazy.nvim spec pointing at the
  plugin repo over SSH (no more local-dir checkout hack)
- README / AGENTS / heph-nvim.md: note the surface lives in its own repo

The CLI/TUI -> nvim integration is unchanged (they shell out to `nvim`
expecting the heph plugin installed). The v1-prototype tech-spec §14 build
record and prior changelog fragments are left as frozen history.

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

2026-06-03 22:42:39 -07:00

4.6 KiB

Raw Permalink Blame History

AGENTS.md

Guidance for Claude Code working in this repository. See also ai-assistance-guide.

Overview

hephaestus — Personal context management system: wiki-style knowledge base and task management.

This is a generated repo, not the template source. C1/C2 changes use feature branches + PRs (tea pr create); noteworthy changes get changelog fragments in docs/changelog.d/.

Rules

Always run mise run ai-docs at session start This will refresh your context with important information you will be assumed to know and follow. Read the full output — never truncate, pipe to head/tail, or skip sections.
Classify the change as C0/C1/C2 before starting (see below) — this determines branching and PR requirements
Generated repos use feature branches + PRs for C1/C2 — checkout main, pull, create branch, open PR via tea pr create. This template source repo usually stays C0/direct-to-main so it remains clean and templatable.
Use changelog fragments in generated repos, not as template residue — docs/changelog.d/<name>.<type>.md Types: feature, bugfix, infra, doc, ai, misc
- Generated repos: add fragments for noteworthy changes
- This template repo: keep docs/changelog.d/ empty except for .gitkeep
Never commit secrets

Change Classification

Before starting work, classify the change:

Class	Name	When to use	Key trait
C0	Quick Fix	Small, low-risk, fix-forward safe	Direct to main, no PR
C1	Human Review	Moderate complexity or risk	Feature branch + PR, docs-first
C2	Mikado Chain	Multi-phase, multi-session, high complexity	Mikado Branch Invariant

C0 — commit directly to main. No branch or PR needed. Fix forward if problems arise.

C1 — in generated repos, use a feature branch with an early PR. In this template source repo, prefer direct cleanups unless the user explicitly wants branch-based review. Search related docs first, write documentation changes before code. Upgrade to C2 if complexity spirals.

C2 — branch mikado/<chain-stem> governed by the Mikado Branch Invariant: all card commits first, then code progress, then card closures. Commits use C2(<chain>): plan/impl/close/finalize convention. Reset the branch when new prerequisites are discovered. Resume with mise run docs-mikado --resume.

See agent-change-process for the full methodology.

Project Structure

A Cargo workspace (Cargo.toml at root) plus repo tooling. Backend feature-complete (all three runtime modes + sync + OIDC); three daily-driver surfaces — heph (CLI) and heph-tui (agenda/triage) in this workspace, plus the hephaestus.nvim Neovim plugin (context/KB) in its own forge repo, eblume/hephaestus.nvim.

./Cargo.toml            # workspace manifest (shared deps + members)
./crates/heph-core/     # core lib: data model, Store trait + SQLite store, extraction,
                        #   recurrence, "what is next?" ranking, op-log/HLC/CRDT (yrs) sync
./crates/hephd/         # daemon: local/server/client modes — unix-socket RPC + HTTP sync/rpc + OIDC auth
./crates/heph/          # CLI (thin client of hephd): next/task/doc/get/export/search/journal/auth
./docs/                 # Diataxis docs (incl. [[design]] + [[v1-prototype-tech-spec]]), Quartz config, release content
./docs/changelog.d/     # towncrier fragments for noteworthy changes
./.dagger/              # Dagger module (src/hephaestus_ci/) backing docs builds and releases
./.forgejo/workflows/   # build + release workflows
./.forgejo/scripts/     # per-project build/release hooks (build runs cargo test once present)
./mise-tasks/           # repo automation via `mise run`

TDD: failing test first → implement to green → commit on green. heph-core is clock-injected (no ambient wall-clock; time is passed in). Spec: v1-prototype-tech-spec (frozen v1 build record); rationale: design (living). Other doc paths via mise run ai-docs; [[like-this]] wiki-links refer to docs/ cards.

Working state (heph self-hosts its roadmap)

Outstanding/future heph work lives as tasks in the Hephaestus project — inspect it before planning:

heph list --project Hephaestus — outstanding tasks (human-readable)
heph list --project Hephaestus --json — JSON rows: node_id, canonical_context_id, attention/state/do_date/recurrence (for scripting/agents)
heph task "<title>" --project Hephaestus -a blue — capture new work (blue = on-deck backlog)

4.6 KiB Raw Permalink Blame History