hafez 1.4.0 → 2.0.0

package/dist/cli/help-agent.js

@@ -1,210 +0,0 @@
-// src/cli/help-agent.ts
-//
-// `hafez help --agent` — the prompt-gate. Plain text, no ANSI, no markdown
-// decoration. Designed for an LLM with zero Hafez context to read once per
-// session and then produce valid batch JSON on first try.
-//
-// Hand-written sections: Preamble + Hard rules (prose, free-form).
-// Generated sections (wrapped in <!-- SECTION:name --> markers so tests can
-// parse them): op-catalog, critical-enums, batch-examples, digest.
-//
-// Generated sections derive from the Op Spec table (batch-ops.ts via
-// schema-introspect.ts), so they cannot drift from the Zod schemas. Do NOT
-// enumerate enum values inside the preamble or hard rules — those come from
-// schema-introspect.ts.
-import { listOps, getEnumValues, getOpExample, getOpSchema } from './schema-introspect.js';
-const PREAMBLE = `# Hafez — Agent Prompt Gate
-
-Hafez is your persistent knowledge graph for projects, entities, captures,
-knowledge notes, and session notes. The \`hafez\` CLI is the ONLY supported
-write path into the vault — never edit files under \`entities/\`, \`knowledge/\`,
-or \`sessions/\` by hand. Every mutation goes through the CLI so the git history,
-SQLite index, and link integrity stay in sync.
-
-Mental model:
-
-- An \`entity\` is tracked work with substance — a bug, a feature, a decision.
-  Entities have status, can have children, and carry a session log. The three
-  entity types are \`capture\` (raw inbox), \`entity\` (standalone tracked item),
-  and \`project\` (scoped effort with deliverables, can have child entities).
-- A \`knowledge\` note is an insight or a plan. Insights distil a pattern or
-  principle and mature through added evidence. Plans are structured steps
-  toward a goal. Knowledge is searchable, linkable, and timestamped.
-- A \`session\` note records what happened in a working session and references
-  the entities it touched. Session notes are created via \`create/session\`
-  and are not indexed in SQLite — they are for narrative, not query.
-- \`capture\` is the quick-inbox path: grab a link or thought, no structure.
-  A capture can later be promoted to entity, project, or knowledge.
-- Entities relate to each other through links: \`parent\` (hierarchy) or
-  \`related\` (soft reference). Use \`link\` / \`unlink\` ops to manage them.
-- Every meaningful update should include a session_log entry so the history
-  of the work is preserved. Sessions are how future-you reconstructs why a
-  decision was made.
-
-Single source of truth: the exact field names, enum values, and op signatures
-below are generated at runtime from the live Zod schema. If a field is not
-listed here, it does not exist — do not invent fields.
-
-## Hard rules (read before writing a batch)
-
-- ALWAYS batch 2+ mutations into one \`hafez batch\` call. Many single-op
-  calls fragment git history and clobber the vault index's atomicity guarantee.
-- NEVER invent field names. If a field is not in \`hafez schema <op>\`, it
-  does not exist. Unknown fields are rejected by the validator with a pointer
-  to the right schema.
-- NEVER write to vault files directly. Always go through the CLI.
-- STRONGLY PREFERRED: include a \`session_log\` on update ops that reflect
-  meaningful work. The validator does not enforce this — omitting it is a
-  code smell, not a hard error.
-- When in doubt, run \`hafez schema <op>\` before writing a batch. Cheap,
-  deterministic, no side effects.
-- Use \`hafez batch --dry-run\` to validate a payload without touching the
-  vault. Same validation as a real apply, zero filesystem mutation.
-
-## Slug contract (create-then-link in one batch)
-
-Slugs are deterministic: slug = slugify(name) — lowercase, non-alphanumeric
-runs collapse to single \`-\`, edges trimmed (\`"Auth Refactor!"\` →
-\`auth-refactor\`). A batch executes sequentially, so later ops may reference
-the slugs of earlier creates in the same batch (\`create\` then \`link\`/\`update\`
-works in one payload). Collisions hard-error — a wrong slug prediction can
-never silently hit an existing document. To verify predictions first:
-\`hafez batch --dry-run\` reports the derived slug for every create op.
-`;
-function renderOpCatalog() {
-    const lines = ['<!-- SECTION:op-catalog -->'];
-    lines.push('Ops (run `hafez schema <name>` for the full field list):');
-    for (const op of listOps()) {
-        const desc = op.description ? ` — ${op.description}` : '';
-        lines.push(`  ${op.name}${desc}`);
-        lines.push(`    → hafez schema ${op.name}`);
-    }
-    lines.push('<!-- /SECTION:op-catalog -->');
-    return lines.join('\n');
-}
-function renderCriticalEnums() {
-    const entries = [
-        ['update.fields.status', 'update.fields.status'],
-        ['update.fields.session_log.type', 'update.fields.session_log.type'],
-        ['update.fields.confidence', 'update.fields.confidence'],
-        ['create-entity.fields.type', 'create-entity.fields.type'],
-        ['create-knowledge.fields.subtype', 'create-knowledge.fields.subtype'],
-        ['link.relation', 'link.relation'],
-    ];
-    const lines = ['<!-- SECTION:critical-enums -->'];
-    lines.push('Critical enums (value lists — values are authoritative):');
-    for (const [label, path] of entries) {
-        const values = getEnumValues(path);
-        if (!values)
-            continue;
-        lines.push(`  ${label} = [${values.join(', ')}]`);
-    }
-    lines.push('<!-- /SECTION:critical-enums -->');
-    return lines.join('\n');
-}
-function renderBatchExamples() {
-    const lines = ['<!-- SECTION:batch-examples -->'];
-    lines.push('Batch JSON shape — wrap one or more ops in an array:');
-    lines.push('');
-    lines.push('  echo \'[...]\' | hafez batch          # POSIX shells');
-    lines.push('  hafez batch --file payload.json     # any platform (PowerShell 5.1 cannot pipe stdin)');
-    lines.push('');
-    lines.push('Minimal example per op (canonical field names; aliased keys stripped):');
-    lines.push('');
-    for (const op of listOps()) {
-        const example = getOpExample(op.name);
-        if (!example)
-            continue;
-        lines.push(`# ${op.name}`);
-        lines.push(JSON.stringify(example, null, 2));
-        lines.push('');
-    }
-    lines.push('<!-- /SECTION:batch-examples -->');
-    return lines.join('\n');
-}
-function renderDigestSection() {
-    const lines = ['<!-- SECTION:digest -->'];
-    lines.push('Session digest — turn end-of-session context into a batch payload.');
-    lines.push('NOT a batch op: it reads its own JSON and prints batch JSON.');
-    lines.push('');
-    lines.push("  echo '<digest-json>' | hafez digest | hafez batch");
-    lines.push('  # No stdin pipes (PowerShell 5.1): hafez digest --file summary.json > ops.json,');
-    lines.push('  # then hafez batch --file ops.json');
-    lines.push('');
-    lines.push('Input fields (`hafez schema digest` for the full schema):');
-    const schema = getOpSchema('digest');
-    for (const [name, field] of Object.entries(schema?.fields ?? {})) {
-        const req = field.optional ? 'optional' : 'required';
-        const desc = field.description ? ` — ${field.description}` : '';
-        lines.push(`  ${name} (${req})${desc}`);
-    }
-    lines.push('');
-    lines.push('Example input:');
-    lines.push(JSON.stringify(getOpExample('digest'), null, 2));
-    lines.push('<!-- /SECTION:digest -->');
-    return lines.join('\n');
-}
-const UPGRADE_SECTION = `## Upgrading hafez itself
-
-\`hafez upgrade\` — checks whether the installed hafez is outdated and prints
-the steps. It NEVER installs: the steps install code and overwrite the user's
-agent instructions, so show them verbatim, get an explicit yes, and only then
-run them. Re-run to verify. Every check outcome exits 0 — being outdated is a
-report, not a gate — so read the output, not the exit code. A non-zero exit
-means the invocation was wrong (exit 2, \`upgrade\` takes no arguments), never
-that a check failed. Not to be confused with \`hafez update\`, which updates
-an entity.
-
-\`--json\` keys: current, latest (null when unverified), comparison
-(behind|equal|ahead|unknown), registryReachable, npmMajor, install
-(registry|dev-checkout), skill (present|absent), skillSource, skillTarget,
-alternativeInstall, steps. \`steps\` is the action list in execution order;
-\`kind: 'command'\` entries are executable, \`kind: 'action'\` entries are
-prose — do not shell out to them. \`alternativeInstall\` is mutually exclusive
-with the install command in \`steps\`; never run both.
-
-Checks the npm registry only (override with \`HAFEZ_REGISTRY_URL\`), so a
-just-cut GitHub Release can read as \`equal\` until it is published.
-
-`;
-const FOOTER = `## Lookup pointers
-
-- \`hafez schema\`                      — list all ops
-- \`hafez schema <op>\`                 — full JSON schema for one op
-- \`hafez schema <op> --examples\`      — working JSON examples per enum value
-- \`hafez batch --dry-run\`             — validate without touching the vault
-`;
-/**
- * Render the full prompt-gate output. Token budget: 1500-3000 tokens when
- * measured as char/3.5. The drift test in tests/cli-help-agent.test.ts
- * enforces the ceiling.
- */
-const EXIT_CODES_SECTION = `## Exit codes
-
-| code | meaning |
-|------|---------|
-| 0 | success |
-| 1 | not found / unknown error |
-| 2 | validation or usage error (bad flags, bad payload, core rejected the write) |
-| 3 | git push failed — the write IS committed locally |
-| 4 | write succeeded but the auto-sync after it failed |
-| 5 | slug already exists |
-| 6 | git commit failed — nothing was written to history |
-| 7 | vault locked by another hafez process — retry when it finishes |`;
-export function renderAgentHelp() {
-    return [
-        PREAMBLE,
-        renderOpCatalog(),
-        '',
-        renderCriticalEnums(),
-        '',
-        renderBatchExamples(),
-        '',
-        renderDigestSection(),
-        '',
-        EXIT_CODES_SECTION,
-        '',
-        UPGRADE_SECTION,
-        FOOTER,
-    ].join('\n');
-}

package/skill/SKILL.md

@@ -1,137 +0,0 @@
----
-name: hafez
-description: >
-  Hafez vault — personal knowledge base of captures, entities, projects, and
-  knowledge notes (subtypes: insight, plan). Use when the user mentions Hafez
-  (or types /hafez), asks what's in the vault ("what am I working on?", "what's
-  stale?"), wants to create or update an entity or knowledge note, at session
-  start to load context for an identifiable topic, at session end to record a
-  digest, when a casually mentioned project name might be a vault entity, or
-  when the user wants to update the tool itself ("update hafez", "upgrade
-  hafez", "is hafez outdated").
----
-
-# Hafez — Vault Operations
-
-All operations go through the `hafez` CLI — it owns reads, writes, validation, and git. Vault files are never edited directly.
-
-If `hafez` is not installed, or `hafez init` reports no vault, stop and follow the setup in the project README (github.com/shrvn-r/hafez) before using this skill. If the vault exists but is empty, run `hafez onboard` and follow what it prints.
-
-## Situation → Command
-
-`hafez help --agent` is the complete, always-current API reference (all commands, flags, batch schema, enum values). This table covers the common situations; consult `help --agent` for anything beyond it.
-
-| Situation | Command |
-|-----------|---------|
-| Read an entity (incl. a project the user mentions) | `hafez read <slug>` |
-| "What am I working on?" / active projects | `hafez query --filter active` |
-| Stale items | `hafez query --filter stale` |
-| Full-text search | `hafez search "<terms>"` (`--kind knowledge` to narrow) |
-| List inbox captures | `hafez query --filter capture` |
-| Children of a project | `hafez query --parent <slug>` |
-| Related entities/knowledge | `hafez query --related-to <slug>` |
-| New workstream | `hafez create entity "<name>" --type project [--brief "context"] [--add-action "task"]` (full flag list in `help --agent`; `--purpose` is project-only) |
-| New plan | `hafez create knowledge "<name>" --subtype plan [--status active\|done]` (plans have Goal/Steps/Dependencies — no `--synthesis`; `--status` is plan-only) |
-| Quick thought, no classification yet | `hafez capture "<name>"` |
-| Promote | `hafez promote <slug> <target>` (capture→entity/project/knowledge, entity→project) |
-| Set handoff context / summary / URI | `hafez update <slug> --brief "text"` / `--description "summary"` / `--resource "https://..."` |
-| Add / complete a next action | `hafez update <slug> --add-action "task"` / `--complete-action "substring"` |
-| Significant milestone (deployed, merged, bug found) | `hafez update <slug> --log "progress: summary" --agent claude` |
-| Link entities | `hafez link <slug> <target> --relation related` (or `parent` when a thread belongs to a project) |
-| Revise a knowledge insight | `hafez update <slug> --synthesis "text"` (`--insight` is an alias) |
-| Back knowledge with evidence / a source | `hafez update <slug> --add-evidence "text"` / `--add-source "url"` |
-| Digest session → batch | `echo '{...}' \| hafez digest \| hafez batch` (no pipes? `--file` on both) |
-
-## Session Start — Context Loading
-
-Load context only when a specific entity slug or topic is identifiable from the user's first message:
-
-1. Run `hafez read <slug>` to load entity context
-2. If the entity has a `parent`, also read the parent at frontmatter depth: `hafez read <parent> --depth frontmatter`
-3. Search for related knowledge (`hafez search "<topic>" --kind knowledge`) and read any relevant note: `hafez read <knowledge-slug>`
-4. Present a brief context line: "Loaded context for {name} (status: {status}, next: {next_action})"
-
-## Search-First Ingest
-
-A new knowledge note is a last resort. When an insight emerges or a source (document, conversation, research) is being processed:
-
-1. Search for existing coverage: `hafez search "<topic>"`, narrowing with `--kind knowledge`.
-2. A note covers the topic → update it: `--synthesis` to revise the main insight, `--add-evidence` to append support, `--add-source` to cite.
-3. Nothing covers it → create it linked from birth (`hafez create knowledge "<name>" --related slug1,slug2`), then write the body via `--synthesis`.
-
-Write `[[wiki links]]` in any knowledge prose (`--brief`, `--synthesis`) to reference related projects, entities, and notes — the CLI does not enforce link syntax; write them naturally in the text. This is what keeps the vault navigable as a wiki.
-
-**Knowledge boundary:** before writing an insight down, ask where it belongs. Useful beyond the current session or repo → vault knowledge note. Specific to one repo's code or workflow → that repo's own docs (CLAUDE.md, README, comments), not the vault.
-
-## Batch Operations
-
-**Rule: Use `hafez batch` when making 2+ mutating calls.** Individual commands auto-commit after each call (and push, when the vault has a remote). Running multiple individual commands back-to-back causes git push races on synced vaults. Batch does all operations in one commit + one push. For a single operation, individual commands are fine — they auto-sync.
-
-```bash
-echo '[
-  {"op":"update","slug":"foo","fields":{"status":"done"}},
-  {"op":"update","slug":"foo","fields":{"session_log":{"type":"progress","summary":"Shipped it","agent":"claude"}}},
-  {"op":"update","slug":"bar","fields":{"add_action":"Write tests"}},
-  {"op":"create","kind":"entity","name":"New Thing","fields":{"type":"project","brief":"Context here.","add_action":"First task"}},
-  {"op":"create","kind":"knowledge","name":"Insight","fields":{"related":["foo"]}},
-  {"op":"create","kind":"session","name":"2026-04-06 Session","fields":{"synthesis":"Summary text"}},
-  {"op":"update","slug":"k1","fields":{"synthesis":"Updated synthesis text"}}
-]' | hafez batch
-```
-
-Batch output includes created slugs: `Batch complete: 3 operations (created: new-thing, insight)`
-
-On shells that can't pipe stdin to native executables (Windows PowerShell 5.1), write the payload to a file and use `hafez batch --file payload.json` — same JSON, same behavior. (`cmd /c "hafez batch < payload.json"` also works.)
-
-**Slug contract.** Slugs derive deterministically from names: lowercase, non-alphanumeric runs become single `-` (`"Auth Refactor!"` → `auth-refactor`). Batch executes sequentially, so later ops can reference the slugs of earlier creates in the same payload — create-then-link works in one batch. Collisions hard-error, so a wrong prediction can't touch the wrong document; `hafez batch --dry-run` reports the derived slug for every create op if you want to verify first.
-
-## Session End — Digest
-
-At the end of a working session (or a natural breakpoint), record what happened:
-
-1. Identify the entities touched this session — read, updated, or created, or whose code was worked on. If unsure whether a name maps to an entity, run `hafez search "<term>"`.
-2. If no entities were touched (pure tooling work with no vault relevance), skip the digest.
-3. Pipe session context through digest into batch (`session_date` is today's real date):
-
-```bash
-echo '{
-  "entities_touched": ["slug-1", "slug-2"],
-  "decisions": ["Decision made", "Another decision"],
-  "narrative": "One to three sentence cross-cutting summary.",
-  "session_date": "2026-07-31",
-  "agent": "claude"
-}' | hafez digest | hafez batch
-```
-
-On shells that can't pipe (PowerShell 5.1), use files instead — digest stays inspectable in the middle: `hafez digest --file summary.json > ops.json`, then `hafez batch --file ops.json`.
-
-Digest adds a session log entry to each touched entity and creates a session note linking them all. Authoritative field docs: `hafez schema digest`.
-
-Digest itself is pure — it only prints batch JSON; `hafez batch` is what writes. If you are unsure the slugs exist, run `hafez digest` alone first: unknown slugs warn on stderr (they are omitted from the output). Fix `entities_touched`, regenerate, and pipe to batch **once** — re-running the full pipe after a successful batch creates a duplicate session note.
-
-**Mid-session updates and the digest coexist.** Point-in-time updates (`--status done`, `--complete-action`, brief changes) happen as they happen — digest adds the overall narrative on top. Digest builds the session summary itself, so the session's closing log entry comes from digest; reserve hand-written `--log` for significant mid-session milestones (deployed, merged, discovered a bug).
-
-Session end is also when knowledge gets written: review what was learned and run Search-First Ingest on anything worth keeping. Knowledge notes are the primary durable output of sessions — not a side effect.
-
-## Periodic Lint
-
-Run at session end or on demand:
-
-```bash
-hafez validate
-hafez query --kind knowledge --sort-by last_reinforced --sort-order asc --limit 20
-```
-
-Surface orphaned notes (no related links) and the least-recently-reinforced knowledge for review or archival. (`--filter` is entity status — knowledge notes have none, so the query command rejects it under `--kind knowledge`.)
-
-## Updating Hafez Itself
-
-"update hafez" means the **tool**. `hafez update` is an entity update — a different thing entirely. Don't confuse them.
-
-1. Run `hafez upgrade`. It checks and prints; it never installs.
-2. Show the user the printed commands **verbatim** and wait for an explicit yes. They install code and overwrite the user's own agent instructions file — never run them unattended, and never run the tarball alternative alongside the npm install.
-3. Run the approved steps, then re-run `hafez upgrade` to verify.
-
-If `hafez upgrade` fails with the literal prefix `Unknown command:`, the installed hafez predates it. Install the current version, re-copy the bundled skill, then run `hafez upgrade` — the README's Updating section (github.com/shrvn-r/hafez) has the exact commands.
-
-`hafez upgrade` also prints the current integration snippet. Compare it against the Hafez block in the user's global instructions file and offer to reconcile differences — don't rewrite their file unasked.