Build / validate (push) Failing after 5s

Details

Fold second-pass design review into v1 spec

Resolve the open tensions surfaced in the pre-Phase-1 second pass over
design.md and tech-spec.md:

- Context items: Fork A index model — body markdown is the source of
  truth; context items are a locally-derived, non-synced index;
  identity is pinned at promotion. Dissolves the body-CRDT vs.
  extraction convergence problem.
- Recurrence: roll-forward in place; drop task_occurrences and
  is_template; advance to next RRULE instance after now (skip misses).
- Identity: deterministic ids for journal/tag (offline-convergent);
  ULID for content nodes and project.
- Mode/sync: orthogonal hub_url spoke capability; everyday device is
  local + hub_url, not server.
- Auth/owner: nullable oidc_sub, friction-free local user, hub-
  authoritative identity, one-time pre-first-sync adoption rewrite.
- Ranking: do_date is a boolean candidacy filter only; late_on is the
  sole urgency signal (global tier); FIFO tiebreak; order expressed as
  a reorderable named-dimension list.
- Modes are plugin-side compositions; add list() and log.tail().
- Frame v1 as a single deliberate C1; misc cleanups (export, health,
  CI nvim runner, README license).

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

2026-05-31 18:08:47 -07:00

3.6 KiB

Raw 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.

First-Time Setup

This repository was instantiated from the project-template Forgejo template. Setup status:

baseUrl in docs/quartz.config.ts set to localhost (update once docs are hosted)
Dagger module renamed to .dagger/src/hephaestus_ci/ (HephaestusCi class)
Fill in the Project Structure section below once the Rust workspace is scaffolded
Fill in license info in README.md (All Rights Reserved / private)

Delete this section once the remaining items are resolved.

This is now 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

./docs/                 # Diataxis docs, Quartz config, and release content
./docs/changelog.d/     # keep only .gitkeep in the template; generated repos add towncrier fragments here
./.dagger/              # Dagger module (src/hephaestus_ci/) backing docs builds and releases
./.forgejo/workflows/   # generic build and release workflows for generated repos
./.forgejo/scripts/     # optional per-project build/release hooks consumed by the workflows
./mise-tasks/           # repo automation via `mise run`

Other code paths will be listed via ai-docs. When you encounter wiki-links ([[like-this]]) it is referring to docs/ cards.

3.6 KiB Raw Blame History