@moreih29/nexus-core 0.1.2 → 0.2.0

package/docs/nexus-layout.md

@@ -0,0 +1,234 @@
+# .nexus/ Directory Layout
+
+This document is the canonical reference for the `.nexus/` directory structure used by all Nexus harnesses. Harnesses read this layout to know where to write, read, and archive runtime state.
+
+---
+
+## Directory Tree
+
+```
+.nexus/
+├── state/                    ← session/branch-scoped (ephemeral)
+│   ├── plan.json
+│   ├── tasks.json
+│   ├── runtime.json
+│   ├── agent-tracker.json
+│   ├── tool-log.jsonl
+│   ├── edit-tracker.json
+│   ├── reopen-tracker.json
+│   └── artifacts/
+├── history.json              ← project-scoped (git-tracked, append-only)
+├── memory/                   ← project-scoped (git-tracked)
+│   └── *.md
+├── context/                  ← project-scoped (git-tracked, nx-sync managed)
+│   └── *.md
+├── rules/                    ← project-scoped (git-tracked, user-defined)
+│   └── *.md
+└── .gitignore
+```
+
+---
+
+## Entry Reference
+
+### `state/`
+
+**Purpose.** Holds all runtime state for the current session or branch. Contents are ephemeral and not meaningful across sessions.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored via `.gitignore`.
+
+**Lifecycle.** Created when the first plan or run cycle begins. Cleared or reset when a new cycle starts or when the session ends. Individual files within `state/` may be archived to `history.json` at cycle close (see `task_close`).
+
+**Owner.** Harness runtime, via lifecycle hooks.
+
+---
+
+#### `state/plan.json`
+
+**Purpose.** Active plan for the current cycle. Contains issues and their decision status.
+
+**Scope.** Session-scoped (one plan per cycle).
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created by `nx-plan` skill at cycle start. Archived into `history.json` at `task_close`. Deleted or overwritten when a new cycle begins.
+
+**Owner.** `nx-plan` skill; updated by plan lifecycle tools.
+
+---
+
+#### `state/tasks.json`
+
+**Purpose.** Task list for the current cycle. Tracks task status, ownership, dependencies, and agent configuration for each unit of work.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created alongside `plan.json` at cycle start. Archived to `history.json` at `task_close`.
+
+**Owner.** `nx-run` skill; updated by task lifecycle tools.
+
+---
+
+#### `state/runtime.json`
+
+**Purpose.** Harness-internal session state that does not belong in plan or task records (e.g., active agent registrations, session-level flags).
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created at session start. Discarded at session end.
+
+**Owner.** Harness runtime.
+
+---
+
+#### `state/agent-tracker.json`
+
+**Purpose.** Records which subagents have been spawned in the current session, their assigned tasks, and their resume-tier classification.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created when the first subagent is spawned. Cleared at session end.
+
+**Owner.** Harness agent-management layer.
+
+---
+
+#### `state/tool-log.jsonl`
+
+**Purpose.** Append-only log of tool invocations made during the current session. Used for auditing, debugging, and post-session analysis.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Appended to throughout the session. Discarded or rotated at session end.
+
+**Owner.** Harness tool-invocation layer.
+
+---
+
+#### `state/edit-tracker.json`
+
+**Purpose.** Tracks which files have been edited in the current session. Used by the bounded resume tier to detect intervening edits before allowing agent reuse.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created on first file edit. Cleared at session end.
+
+**Owner.** Harness file-edit hooks.
+
+---
+
+#### `state/reopen-tracker.json`
+
+**Purpose.** Records tasks or plan issues that have been reopened within the current cycle, to prevent infinite reopen loops.
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Created on first reopen event. Cleared at cycle end.
+
+**Owner.** Task and plan lifecycle tools.
+
+---
+
+#### `state/artifacts/`
+
+**Purpose.** Stores intermediate and final deliverables produced by subagents during the current cycle (e.g., reports, synthesized documents, analysis outputs).
+
+**Scope.** Session-scoped.
+
+**Git tracking.** Ignored.
+
+**Lifecycle.** Files are written here by subagents during a run cycle. The directory persists for the session; individual files may be promoted to project-level locations by Lead before the cycle closes.
+
+**Owner.** Subagents writing deliverables; Lead controls promotion.
+
+---
+
+### `history.json`
+
+**Purpose.** Append-only archive of completed plan and task cycles. Each completed cycle contributes one record. Used to reconstruct project history and provide context for future plans.
+
+**Scope.** Project-scoped.
+
+**Git tracking.** Tracked (committed to the repository).
+
+**Lifecycle.** Created on first `task_close`. Records are appended at each subsequent `task_close`. Never truncated or overwritten; only appended.
+
+**Owner.** `task_close` lifecycle tool.
+
+---
+
+### `memory/`
+
+**Purpose.** Stores lessons learned, reference notes, and durable observations captured with the `[m]` tag. Each note is a standalone Markdown file.
+
+**Scope.** Project-scoped.
+
+**Git tracking.** Tracked.
+
+**Lifecycle.** Files are created when Lead or a subagent records a memory entry. They persist indefinitely. Stale entries are merged or removed via `[m:gc]`.
+
+**Owner.** Memory-store inline action; garbage-collected by `[m:gc]`.
+
+---
+
+### `context/`
+
+**Purpose.** Holds design documents and architecture philosophy that describe the project's principles and current state. Managed by the `nx-sync` skill, which keeps these documents current with the actual codebase.
+
+**Scope.** Project-scoped.
+
+**Git tracking.** Tracked.
+
+**Lifecycle.** Files are created or updated by `[sync]`. They should be refreshed whenever the project's architecture or design intent changes significantly.
+
+**Owner.** `nx-sync` skill.
+
+---
+
+### `rules/`
+
+**Purpose.** Contains user-defined project rules created with the `[rule]` tag. Rules constrain agent behavior for this specific project and take precedence over default behavior.
+
+**Scope.** Project-scoped.
+
+**Git tracking.** Tracked.
+
+**Lifecycle.** Files are created by the rule-store inline action and persist indefinitely. Users are responsible for removing obsolete rules.
+
+**Owner.** Rule-store inline action (`[rule]`); maintained by users.
+
+---
+
+### `.gitignore`
+
+**Purpose.** Ensures that ephemeral session state is not committed to the repository while project-scoped files remain tracked.
+
+**Scope.** Project-scoped.
+
+**Git tracking.** Tracked.
+
+**Lifecycle.** Created during project initialization. Updated when new ephemeral paths are added to `state/`.
+
+**Owner.** Nexus initialization tooling.
+
+**Convention.** The `.gitignore` inside `.nexus/` must ignore the `state/` directory and all its contents. The following entries must be tracked and must not appear in `.gitignore`: `memory/`, `context/`, `rules/`, `history.json`.
+
+Minimal required content:
+
+```
+state/
+```

package/docs/nexus-state-overview.md

@@ -0,0 +1,185 @@
+# Nexus State File Overview
+
+This document is the normative specification for all files and directories that constitute Nexus runtime and project state. It defines each file's purpose, lifecycle, git-tracking status, and the tools that read or write it.
+
+The Nexus state layout is divided into two categories:
+
+- **Session-scoped state** — created and deleted within a single planning/execution cycle; not git-tracked.
+- **Project-scoped content** — persists across cycles; git-tracked as part of the repository.
+
+---
+
+## State File Reference
+
+### `.nexus/state/plan.json`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Session |
+| Git-tracked | No |
+| Created by | `plan_start` |
+| Deleted by | `plan_start` (auto-archive of prior session), `task_close` |
+
+**Purpose.** Holds the active planning session. Contains the plan `id`, `topic`, `research_summary`, `created_at`, and the ordered list of `PlanIssue` objects. Each issue records its `id`, `title`, `status` (`"pending"` or `"decided"`), and — once decided — the `decision` summary along with optional `how_agents`, `how_summary`, and `how_agent_ids` fields.
+
+**Creation trigger.** `plan_start` writes this file after archiving any existing session. The `id` is set to one greater than the highest plan `id` found in `history.json`.
+
+**Deletion trigger.** `task_close` archives the file's contents into `history.json` and then deletes it. `plan_start` also deletes a pre-existing `plan.json` when starting a new session (archiving it first).
+
+**Tool access.**
+
+| Tool | Access |
+|------|--------|
+| `plan_start` | Write (creates) |
+| `plan_status` | Read |
+| `plan_update` | Read + Write |
+| `plan_decide` | Read + Write |
+| `task_close` | Read + Delete |
+| `context` | None |
+
+---
+
+### `.nexus/state/tasks.json`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Session |
+| Git-tracked | No |
+| Created by | `task_add` (on first call) |
+| Deleted by | `task_close` |
+
+**Purpose.** Holds the active task list. Contains a top-level `goal` string, a `decisions` string array (key decisions from the plan session), and a `tasks` array. Each task records `id`, `title`, `context`, optional `approach`, `acceptance`, `risk`, `status`, `deps`, `plan_issue`, `owner`, `owner_agent_id`, `owner_reuse_policy`, and `created_at`.
+
+**Creation trigger.** `task_add` initializes this file with `{ goal: "", decisions: [], tasks: [] }` when it does not yet exist, then immediately appends the first task.
+
+**Deletion trigger.** `task_close` archives the task list into `history.json` and deletes this file.
+
+**Tool access.**
+
+| Tool | Access |
+|------|--------|
+| `task_add` | Write (creates if absent) |
+| `task_list` | Read |
+| `task_update` | Read + Write |
+| `task_close` | Read + Delete |
+| `context` | Read |
+
+---
+
+### `.nexus/history.json`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Project |
+| Git-tracked | Yes |
+| Created by | `plan_start` or `task_close` (on first archive) |
+| Deleted by | Never |
+
+**Purpose.** Append-only ledger of completed planning and execution cycles. Each entry (a "cycle") captures `completed_at`, `branch`, the full `plan` object (or `null`), and the full `tasks` array at time of closure.
+
+**Creation trigger.** Created automatically by `plan_start` when it archives a prior session, or by `task_close` when it archives the current cycle. If the file already exists, new cycles are appended to the `cycles` array.
+
+**Deletion trigger.** Never deleted. This file is the permanent project record.
+
+**Tool access.**
+
+| Tool | Access |
+|------|--------|
+| `plan_start` | Read + Write (archive pre-existing plan) |
+| `task_close` | Read + Write (archive current cycle) |
+| `history_search` | Read |
+
+---
+
+### `.nexus/state/runtime.json`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Session |
+| Git-tracked | No |
+| Created by | Session start (harness hook) |
+| Deleted by | Session end (harness hook) |
+
+**Purpose.** Holds session-level runtime metadata established when the harness initializes (e.g., session identifiers, harness version, environment properties). This file is managed entirely by the harness layer; no Nexus MCP tool writes to it.
+
+**Creation trigger.** Written by the harness during session initialization before any tool is called.
+
+**Deletion trigger.** Removed by the harness upon session teardown.
+
+**Tool access.** Read-only by the harness infrastructure. No Nexus MCP tool listed in this specification reads or writes this file directly.
+
+---
+
+### `.nexus/state/agent-tracker.json`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Session |
+| Git-tracked | No |
+| Created by | Session start (harness hook) |
+| Deleted by | Session end (harness hook) |
+
+**Purpose.** Tracks agent instance activity during the session — which agents were spawned, their instance IDs, and what artifacts they touched. Used by the harness to evaluate `owner_reuse_policy` on subsequent `task_add` calls and to support agent resume.
+
+**Creation trigger.** Initialized by the harness at session start.
+
+**Deletion trigger.** Removed by the harness upon session teardown.
+
+**Tool access.** Managed exclusively by harness hooks. No Nexus MCP tool listed in this specification writes to this file; `task_add` reads the `owner_agent_id` field from tasks to inform the harness, but does not access `agent-tracker.json` directly.
+
+---
+
+### `.nexus/state/artifacts/`
+
+| Attribute | Value |
+|-----------|-------|
+| Scope | Session |
+| Git-tracked | No |
+| Created by | `artifact_write` |
+| Deleted by | Session end (harness cleanup) or manual removal |
+
+**Purpose.** Stores named artifact files produced by agents during a session — research outputs, synthesis documents, analysis reports, and similar deliverables. Each file is written by a single call to `artifact_write` and may be overwritten by subsequent calls with the same filename.
+
+**Creation trigger.** The directory is created on demand by the first `artifact_write` call in a session.
+
+**Deletion trigger.** Session-scoped; not archived by `task_close`. Persistence beyond the session is the caller's responsibility.
+
+**Tool access.**
+
+| Tool | Access |
+|------|--------|
+| `artifact_write` | Write (creates directory if absent, writes file) |
+
+---
+
+## Content File Conventions
+
+The following directories hold project-scoped knowledge files. All are git-tracked and persist across sessions and cycles.
+
+### `.nexus/memory/*.md`
+
+**Purpose.** Stores lessons learned, reference notes, and factual anchors accumulated during project work. Each file is a discrete note tagged with the `[m]` convention. Files are authored and updated by the Lead agent in response to `[m]` tags in conversation.
+
+**Lifecycle.** Created manually or by Lead; updated incrementally. Stale entries are garbage-collected via the `[m:gc]` convention. No Nexus MCP tool writes to this directory.
+
+**Format.** Plain Markdown. An optional `<!-- tags: tag1, tag2, tag3 -->` comment may appear as the first line to support filtering. No required frontmatter schema.
+
+---
+
+### `.nexus/context/*.md`
+
+**Purpose.** Stores design principles, architecture philosophy, and structural decisions that define how the project should evolve. These files represent the canonical design record and are the primary input for the `nx-sync` skill.
+
+**Lifecycle.** Created and updated by the `nx-sync` skill, which scans the current project state and reconciles it with existing context documents. Human authors may also edit these files directly. No Nexus MCP tool writes to this directory during normal execution.
+
+**Format.** Plain Markdown. An optional `<!-- tags: tag1, tag2, tag3 -->` comment may appear as the first line. No required frontmatter schema.
+
+---
+
+### `.nexus/rules/*.md`
+
+**Purpose.** Stores user-defined rules that govern agent behavior, coding conventions, and process constraints specific to this project. Rules are authored by the user via the `[rule]` and `[rule:*]` tag conventions.
+
+**Lifecycle.** Created by the Lead agent when the user asserts a rule via the `[rule]` tag. Rules persist indefinitely unless explicitly removed or superseded. No Nexus MCP tool writes to this directory.
+
+**Format.** Plain Markdown. An optional `<!-- tags: tag1, tag2, tag3 -->` comment may appear as the first line to support categorization. No required frontmatter schema.