djournal 0.1.0

package/.agents/adapters/contract.md

@@ -0,0 +1,48 @@
+# Journal Harness Adapter Contract
+
+Harness adapters improve compliance with the journal workflow. They are not a
+second workflow engine and do not own durable state.
+
+## Semantic events
+
+| Event | Adapter behavior |
+| --- | --- |
+| `session_start` | Inject the active work name and tell the agent to follow `AGENTS.md` |
+| `prompt_submit` | Remind the agent to classify the request; preserve explicit opt-out |
+| `mutation_observed` | Optional ephemeral reminder only; never write state |
+| `before_compact` | Optional reminder to preserve material state before context loss |
+| `stop` | Validate the final journal status marker and request one closure pass |
+
+An adapter may omit events its harness cannot support reliably. Instruction-only
+behavior remains the compatibility baseline.
+
+## Input
+
+The shared checker accepts one JSON object on stdin. It uses only stable fields:
+
+- `cwd`
+- `hook_event_name`
+- `prompt`
+- `last_assistant_message`
+- `stop_hook_active`
+
+It does not parse conversation transcripts. Harness wrappers may normalize
+native payloads to these names.
+
+## Output
+
+- Start and prompt events return `hookSpecificOutput.additionalContext`.
+- Stop returns `{}` when closure is valid or no journal is installed.
+- Stop returns `{ "decision": "block", "reason": "..." }` for one retry when
+  the final status marker is missing or invalid.
+- Malformed input and absent journal roots fail open with a bounded stderr
+  diagnostic and exit code zero.
+
+## Invariants
+
+- Hooks are read-only.
+- `stop_hook_active: true` always permits stopping.
+- `closed` markers must resolve inside `.journal/work/` to an existing Markdown
+  spine entry.
+- Adapters do not infer task meaning from file changes or unstable transcripts.
+- Adding a harness must not change `AUTOMATION.md` semantics.

package/.agents/adapters/shared/journal-hook.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const MARKER = /<!--\s*journal-status:\s*(closed|not-needed|off)(?:\s+([^>]*?))?\s*-->\s*$/i;
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { input += chunk; });
+    process.stdin.on("end", () => resolve(input));
+  });
+}
+
+function findRoot(start) {
+  let current = path.resolve(start || process.cwd());
+  while (true) {
+    if (fs.existsSync(path.join(current, "AGENTS.md")) &&
+        fs.existsSync(path.join(current, ".agents", "rules", "AUTOMATION.md"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function activeWork(root) {
+  try {
+    const state = JSON.parse(fs.readFileSync(path.join(root, ".journal", "state.json"), "utf8"));
+    if (typeof state.active_work_name !== "string" || !state.active_work_name) return null;
+    const work = path.join(root, ".journal", "work", state.active_work_name, "work.md");
+    return fs.existsSync(work) ? state.active_work_name : null;
+  } catch {
+    return null;
+  }
+}
+
+function context(event, message) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: message,
+    },
+  };
+}
+
+function validateClosedPath(root, value) {
+  if (!value) return false;
+  const relative = value.trim().replaceAll("\\", "/");
+  if (!relative.endsWith(".md") || path.isAbsolute(relative)) return false;
+  const resolved = path.resolve(root, relative);
+  const journalRoot = path.resolve(root, ".journal", "work") + path.sep;
+  if (!resolved.startsWith(journalRoot)) return false;
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) return false;
+  return resolved.split(path.sep).join("/").includes("/journal/");
+}
+
+function handle(payload) {
+  const event = payload.hook_event_name;
+  const root = findRoot(payload.cwd);
+  if (!root) return {};
+
+  if (event === "SessionStart") {
+    const work = activeWork(root);
+    const suffix = work ? ` Active work: ${work}.` : " No valid active work is selected.";
+    return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${suffix}`);
+  }
+
+  if (event === "UserPromptSubmit") {
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    if (/\bjournal\s*:\s*off\b/i.test(prompt)) {
+      return context(event, "Journal opt-out applies to this request. End with the journal-status: off marker.");
+    }
+    return context(event, "Classify this request using the ambient journal workflow. Close meaningful changed state before the final response, without adding ceremony to read-only or trivial work.");
+  }
+
+  if (event !== "Stop") return {};
+  if (payload.stop_hook_active === true) return {};
+
+  const message = typeof payload.last_assistant_message === "string"
+    ? payload.last_assistant_message
+    : "";
+  const match = message.match(MARKER);
+  if (!match) {
+    return {
+      decision: "block",
+      reason: "Perform the journal closure checkpoint from AGENTS.md. Journal meaningful changed state if needed, then end with one valid hidden journal-status marker.",
+    };
+  }
+
+  if (match[1].toLowerCase() === "closed" && !validateClosedPath(root, match[2])) {
+    return {
+      decision: "block",
+      reason: "The journal-status closed marker must reference an existing repository-relative Markdown spine entry under .journal/work/<work>/journal/.",
+    };
+  }
+  return {};
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    const payload = raw.trim() ? JSON.parse(raw) : {};
+    process.stdout.write(`${JSON.stringify(handle(payload))}\n`);
+  } catch (error) {
+    process.stderr.write(`journal hook skipped: ${error.message}\n`);
+    process.stdout.write("{}\n");
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { handle };

package/.agents/rules/AUTOMATION.md

@@ -0,0 +1,84 @@
+# Ambient Journal Automation Rules
+
+These rules coordinate existing journal skills. They do not replace the file,
+metadata, link, state, or safety rules those skills own.
+
+## Task classification
+
+Classify each request before acting:
+
+| Class | Examples | Default behavior |
+| --- | --- | --- |
+| Read-only | explain, inspect, review, answer status | Recall or resume only when history matters; do not write a closing entry |
+| Trivial mutation | typo, tiny formatting or config correction | Resume only when context matters; validate; journal only if durable project state changed |
+| Meaningful mutation | feature, fix, migration, behavioral change | Resume; plan when warranted; implement; validate; journal |
+| Durable knowledge | research, decision, canonical documentation | Resume; use the matching supporting skill; journal when work state changed |
+
+Classification requires semantic judgment. File changes alone do not establish
+that a task was meaningful.
+
+## Start checkpoint
+
+- If the user says `journal: off`, skip ambient journal reads and writes for the
+  request unless another explicit instruction requires them.
+- If `.journal/state.json` selects active work, use `resume` when historical
+  context can affect the result.
+- If no active work exists and the request clearly starts a new durable work
+  stream, use `init-work`. Ask only when its identity or scope is materially
+  ambiguous.
+- Do not create a work item for a read-only question or incidental edit.
+
+## Plan threshold
+
+Use `plan` before implementation when the work has multiple dependent phases,
+meaningful design choices, risky migration behavior, cross-component effects,
+or a validation strategy that should survive the current conversation.
+
+Skip a durable plan for changes that are local, obvious, reversible, and easy to
+validate. Existing user-approved plans do not need another plan.
+
+## Work checkpoint
+
+- Use `research-codebase` or `research-web` only when the findings should remain
+  durable evidence.
+- Use `decision` when an accepted choice and its rationale constrain later work.
+- Use `document` for a durable synthesized reference.
+- Never copy semantic write logic into an orchestration hook or adapter.
+
+## Closure checkpoint
+
+Before the final response:
+
+1. Decide whether meaningful journal state changed.
+2. If it did, use `journal` once after validation and reference supporting
+   entries actually used.
+3. Check the latest spine entry before writing. Update or skip when a new entry
+   would describe the same completed outcome.
+4. If validation failed, record the accurate partial or blocked state rather
+   than claiming completion.
+5. End the response with one status marker defined in root `AGENTS.md`.
+
+`closed` requires a repository-relative path to an existing spine entry.
+`not-needed` means the task was read-only or too small to change durable state.
+`off` means the user explicitly opted out for the request.
+
+## Hook boundary
+
+Harness hooks may:
+
+- inject these workflow reminders;
+- report active-work metadata;
+- validate the final status marker and referenced entry;
+- request at most one additional closure pass.
+
+Hooks must not create work items, plans, research, decisions, documents, or
+journal entries. They must safely no-op when the journal is absent and must not
+read unstable transcript formats to infer work.
+
+## Failure behavior
+
+- A hook failure warns but does not replace journal safety or state rules.
+- A missing or invalid active state uses the bounded error from `STATE.md` when
+  a semantic write is required.
+- An unsupported, disabled, or untrusted hook falls back to these instructions.
+- The hook-provided `stop_hook_active` guard permits only one continuation pass.

package/.agents/rules/FEAT.md

@@ -0,0 +1,83 @@
+# Work Item Rules
+
+Agent configuration lives under `.agents/`. Durable journal data lives under
+`.journal/`. Skills MUST read rules from `.agents/rules/` and MUST NOT write
+runtime work data into `.agents/`.
+
+Read these rules together with:
+
+- `.agents/rules/METADATA.md`
+- `.agents/rules/LINKS.md`
+- `.agents/rules/SAFETY.md`
+- `.agents/rules/STATE.md`
+
+## Work item layout
+
+When creating a work item, create this structure:
+
+```text
+.journal/work/YYYY-MM-DD-NN-work-name/
+├── work.md
+├── journal/
+├── _research/
+├── docs/
+└── decisions/
+```
+
+- `work.md`: canonical work-item metadata and a short human-readable overview
+- `journal/`: chronological spine entries
+- `_research/`: supporting codebase and web research
+- `docs/`: supporting synthesized references
+- `decisions/`: supporting standalone decisions
+
+## Naming
+
+- Folder format: `YYYY-MM-DD-NN-work-name`.
+- Date is the UTC creation date.
+- `NN` is the next two-digit sequence for work items created that day.
+- `work-name` is lowercase kebab-case, descriptive, and unique.
+- Avoid spaces and special characters other than hyphens.
+- The folder name MUST equal `slug` in `work.md`.
+
+Example: `2026-06-29-01-portable-journal-skill-improvements`.
+
+## Initialization
+
+`init-work` MUST:
+
+1. Inspect existing work folders to select a non-conflicting daily sequence.
+2. Create the complete directory structure above.
+3. Resolve identity according to `METADATA.md`.
+4. Generate one stable `wi_` UUIDv7.
+5. Create `work.md` with all required work-item metadata.
+6. Default to `status: active` and `visibility: local_only`.
+7. Set `createdAt` and `updatedAt` to the same current UTC timestamp.
+8. Set `.journal/state.json` to the new slug according to `STATE.md`.
+
+Work items are projects, not repositories. A project MAY span many repositories,
+branches, and working directories. Do not create a new work item merely because
+the repository changed.
+
+## Lifecycle
+
+Allowed status values:
+
+- `draft`: created but not yet meaningful active work
+- `active`: current ongoing work
+- `paused`: intentionally inactive but expected to resume
+- `completed`: intended outcome achieved
+- `archived`: retained history with no expected continuation
+
+Status updates preserve `createdAt`, update `updatedAt`, and never alter `id` or
+`slug`. Visibility changes require an explicit user request.
+
+Only one work item is selected as active in `.journal/state.json`, but other work
+items may remain in `active` status. Active selection and lifecycle status are
+different concepts.
+
+## Legacy work items
+
+A historical folder without `work.md` remains readable. Resume and recall may
+infer its slug and title from the folder name. Audit flags the missing file;
+reconcile may create it using deterministic legacy timestamps and
+`source`/identity rules without modifying existing entry bodies.

package/.agents/rules/JOURNAL.md

@@ -0,0 +1,127 @@
+# Journal Entry Rules
+
+Read these rules together with:
+
+- `.agents/rules/METADATA.md`
+- `.agents/rules/LINKS.md`
+- `.agents/rules/SAFETY.md`
+
+Markdown remains the source of truth. Every new entry MUST contain valid
+canonical frontmatter followed by a concise, human-readable body.
+
+## Entry locations and roles
+
+Role is derived from `entryType`; never store a separate `role` field.
+
+| Directory | Entry types | Derived role |
+| --- | --- | --- |
+| `journal/` | `plan`, `implementation`, `status`, `manual` | spine |
+| `_research/` | `research` | supporting |
+| `docs/` | `doc` | supporting |
+| `decisions/` | `decision` | supporting |
+
+Supporting entries stand alone and are linked from spine or other supporting
+entries. They do not add independent steps to the project timeline.
+
+## Filenames
+
+- Spine: `YYYY-MM-DD-NN-brief-description.md`
+- Codebase research: `YYYY-MM-DD-NN-codebase-topic.md`
+- Web research: `YYYY-MM-DD-NN-web-topic.md`
+- Documents: `YYYY-MM-DD-NN-topic.md`
+- Decisions: `YYYY-MM-DD-NN-decision-topic.md`
+
+`NN` is the next sequence within the destination directory for that UTC date.
+Filenames are descriptive, lowercase kebab-case. Entry identity comes from the
+stable `ent_` UUIDv7, not the filename or entry number.
+
+## Required spine body
+
+Every spine entry MUST include these sections, adapted to its entry type:
+
+### Project Timeline
+
+A chronological index of the work item's spine. Supporting entries appear only
+as links from the relevant spine entry.
+
+### Current State
+
+- components and their working/partial/broken status
+- validation status with real counts when available
+- key files and their current purpose
+
+For a plan entry, this may be named `Current State Analysis`.
+
+### Work Done This Session
+
+- specific work performed
+- problems resolved
+- decisions made and why
+- deterministic evidence such as paths, commits, and validation results
+
+For a plan entry, replace this with the feature overview, proposed design, and
+phased implementation plan. Do not claim planned work was implemented.
+
+### Next Steps
+
+- concrete actions in priority order
+- known blockers and unresolved questions
+
+Include architecture notes only when architecture changed or the plan proposes
+an architectural change. Keep diagrams small and useful.
+
+## Type-specific content
+
+- `plan`: problem, goals, non-goals, current state, design, phases, tests, edge
+  cases, open questions, and next steps
+- `implementation`: changes, rationale, files, validation, commits, current state,
+  and next steps
+- `status`: current state, evidence, blockers, and next steps; no invented work
+- `manual`: user-supplied or exceptional spine note following the core sections
+- `research`: question, summary, sources/key files, findings, and open questions
+- `doc`: standalone synthesized reference with source links
+- `decision`: context, options, decision, rationale, consequences, and supersession
+
+## Frontmatter and links
+
+- Follow `METADATA.md` exactly.
+- New output MUST have a useful one- or two-sentence `summary`.
+- Skill-created files use `source: manual`.
+- Entry `workItemId` MUST match the active work item's `work.md`.
+- Store outgoing typed links according to `LINKS.md`.
+- A human-readable body citation may accompany a structured link but does not
+  replace it.
+- On edits, preserve `id` and `createdAt`; update `updatedAt`.
+
+## Project timeline and compaction
+
+The latest spine entry is the primary retrieval index.
+
+- Recent entries may be listed individually.
+- Older entries may be summarized into chronological milestone ranges when the
+  timeline threatens the 100-200 line target.
+- Keep decisions, regressions, releases, and major architecture changes visible
+  as individual milestones regardless of age.
+- Preserve entry numbers as recorded, including historical forks or gaps.
+- Never delete or rewrite original entries as part of compaction.
+- The timeline must still let a reader locate detailed source entries.
+
+## Evidence and safety
+
+- Include real file paths, commit hashes, PRs, commands, and test counts when known.
+- Do not fabricate line numbers, test results, commits, or links.
+- Prefer summaries and diff statistics over full diffs.
+- Truncate failure output to the smallest useful redacted excerpt.
+- Follow `SAFETY.md` before every write.
+
+## Legacy entries
+
+Markdown without frontmatter remains valid historical input. Infer metadata
+best-effort from its directory, filename, and first heading. Do not block resume
+or recall. Audit reports missing metadata; reconcile may add it conservatively
+without rewriting the body or renumbering the entry.
+
+## Compactness
+
+Target 100-200 lines for a spine entry. Supporting entries may be longer when
+the topic requires it, but should synthesize rather than dump source material.

package/.agents/rules/LINKS.md

@@ -0,0 +1,96 @@
+# Entry Link Rules
+
+Links form a directed graph between any two journal entries. The source entry owns
+the outgoing link in its frontmatter; incoming links are derived by scanning all
+entries.
+
+Read `.agents/rules/METADATA.md` before creating or modifying links.
+
+## Link shape
+
+Store outgoing links in the source entry's frontmatter:
+
+```yaml
+links:
+  - id: lnk_0197c4d2-7b20-7abc-8d2e-0123456789ab
+    fromEntryId: ent_0197c4d2-7b20-7abc-8d2e-0123456789ab
+    toEntryId: ent_0197c4d3-1010-7def-8abc-0123456789ab
+    relation: references
+    createdAt: "2026-06-29T12:05:00.000Z"
+    targetPath: ../_research/codebase-portable-journal-skill-improvements.md
+```
+
+Canonical fields:
+
+- `id`: stable `lnk_` UUIDv7
+- `fromEntryId`: MUST equal the containing entry's `id`
+- `toEntryId`: MUST equal the target entry's `id`
+- `relation`: `references`, `supersedes`, or `relates_to`
+- `createdAt`: canonical ISO-8601 UTC timestamp
+
+Filesystem addition:
+
+- `targetPath`: required relative path from the source file to the target file
+
+Do not add `referencedBy`; it is derived from other entries' outgoing links.
+
+## Relation semantics
+
+- `references`: source uses or cites target for context. This is the default.
+- `supersedes`: source replaces or rolls back target. Direction is newer to older.
+- `relates_to`: loose association or evolution when neither other relation fits.
+
+The entry endpoints carry what they are through `entryType`; the relation says
+why they are connected. Any entry type may link to any other entry type.
+
+## Invariants
+
+- The tuple `(fromEntryId, toEntryId, relation)` MUST be unique.
+- `fromEntryId` and `toEntryId` MUST resolve to existing entries.
+- `targetPath` MUST resolve to the same entry as `toEntryId`.
+- Paths MUST be relative, use `/`, and include the `.md` extension.
+- IDs remain authoritative across renames; paths are the human/filesystem locator.
+- A path-only Markdown citation does not replace the structured link.
+- Do not create a reciprocal link unless it has independent directional meaning.
+- Do not create self-links.
+
+Cross-work-item links are allowed.
+Use the correct relative path and target ID.
+
+## Spine and supporting entries
+
+The role is derived from `entryType`:
+
+- Spine: `plan`, `implementation`, `status`, `manual`
+- Supporting: `research`, `doc`, `decision`
+
+A supporting entry is orphaned when no entry links to it. Audit should flag an
+orphan. Reconcile may add a link only when the source entry is unambiguous.
+
+Typical relationships:
+
+- plan `references` research
+- implementation `references` a doc
+- implementation `references` a decision
+- decision `references` the research supporting its rationale
+- newer decision `supersedes` an older decision
+- entries in an evolution chain `relates_to` one another
+
+## Link maintenance
+
+- Creating or removing a link updates the source entry's `updatedAt`.
+- Renaming a target updates every matching `targetPath`, but preserves link and
+  entry IDs and `createdAt`.
+- Removing an incorrect link removes only the link object. Never delete either
+  entry as a side effect.
+- When a path is broken but `toEntryId` resolves uniquely, reconcile may repair
+  `targetPath`.
+- When an ID or target is ambiguous, report it for human review.
+- Duplicate entry numbers do not affect link identity and are never auto-fixed.
+
+## Legacy references
+
+For legacy files, body references to `_research/*.md`, `docs/*.md`,
+`decisions/*.md`, or another journal entry are evidence of a potentially missing structured link. Audit
+reports the discrepancy. Reconcile may create the link only after resolving one
+unique target and confirming the relation from context.