@first-tree-ai/context-tree 0.0.1 → 0.1.0

package/docs/specification.md

@@ -0,0 +1,74 @@
+# Context Tree Format Specification
+
+## Repository and root
+
+A shared Context Tree lives in a `github.com` repository identified as
+`OWNER/REPO`. GitHub commit SHAs identify exact shared snapshots. The package
+still operates on local clones and worktrees because validation and editing are
+filesystem operations.
+
+The tree root is a real directory containing `NODE.md`. Optional `SCOPE.md`
+must be a regular UTF-8 file with schema-version-1 frontmatter and non-empty
+prose:
+
+```yaml
+---
+schemaVersion: 1
+relatedRepositories:
+  - https://github.com/acme/service.git
+---
+```
+
+`relatedRepositories` remains provider-neutral and accepts at most 64
+credential-free HTTP(S), `ssh://`, or scp-style SSH references. It describes
+related source repositories; it does not identify the Context Tree repository.
+
+## Nodes and content classes
+
+The root requires `NODE.md`. A semantic directory represented as a node also
+contains `NODE.md`; organizational directories containing Markdown leaves need
+not. Normal nodes require a non-empty `title` and `owners` array. Optional
+`description` is non-empty prose, and optional `soft_links` contains
+tree-root-relative Markdown files or node directories.
+
+- `normal`: root and durable domain decisions.
+- `archive-supporting`: evidence beneath `raw-context/`.
+- `member`: ownership and routing beneath `members/`.
+- `repo-infra`: dot paths, generated output, instructions, build, and CI files.
+
+Normal content must not depend on archive-supporting content. Symlinks fail
+closed: they may not escape the tree, cross content-class boundaries, or stand
+in for domain directories. Reads default to normal content. Glob patterns are
+case-sensitive and segment-local.
+
+`members/NODE.md` is the member index. Every direct member directory requires a
+`NODE.md` with title, owners, type (`human` or `agent`), role, and domains.
+
+## Public contracts
+
+CLI JSON uses `schemaVersion: 1`. Exported strict Zod schemas are the source of
+truth for library and CLI wire contracts. Unknown output properties are
+rejected. Successful command results and runtime or argument failures emit one
+JSON object on stdout; help and version output remain plain text. An invalid
+`verify` report is still emitted and the command exits with status 1.
+
+`policy` returns `content` and `schemaVersion`. `read` returns the root, target,
+schema version, and selected entries. `verify` returns the root, schema version,
+validity, findings, and content-class counts. None includes a tree digest or
+per-entry digest. The Git commit SHA is recorded by the surrounding host Git
+workflow rather than computed by the core.
+
+## Lifecycle
+
+Scaffolding always creates a validation workflow pinned to the package version
+that generated it. New repositories always initialize and publish `main`,
+regardless of the user's Git configuration; the generated workflow filters
+pushes to `main`. Hosted reads require an explicit `OWNER/REPO` and branch, a
+clean matching checkout, fast-forward refresh, validation, and a reported
+commit SHA. Explicitly authorized stale reads are labeled and remain read-only.
+
+Every write starts in an isolated worktree at a freshly fetched base commit.
+The base and final tree must validate; all edits are direct, necessary Markdown
+changes; the full diff is reviewed; publication uses a non-force task-branch
+push and GitHub PR. An invalid base permits only an explicitly requested,
+validator-scoped repair PR. No workflow merges automatically.

package/examples/basic/NODE.md

@@ -0,0 +1,11 @@
+---
+title: "Example Context Tree"
+description: "A small valid Context Tree fixture."
+owners: [example-owner]
+---
+
+# Example Context Tree
+
+## Decision
+
+Durable system decisions live under `systems/`.

package/examples/basic/SCOPE.md

@@ -0,0 +1,7 @@
+---
+schemaVersion: 1
+relatedRepositories:
+  - https://github.com/first-tree-ai/context-tree.git
+---
+
+This example covers the portable Context Tree package and its public format.

package/examples/basic/members/NODE.md

@@ -0,0 +1,6 @@
+---
+title: "Members"
+owners: [example-owner]
+---
+
+# Members

package/examples/basic/members/example-owner/NODE.md

@@ -0,0 +1,10 @@
+---
+title: "Example Owner"
+owners: [example-owner]
+type: human
+role: "Maintainer"
+domains:
+  - "systems"
+---
+
+# Example Owner

package/examples/basic/systems/NODE.md

@@ -0,0 +1,7 @@
+---
+title: "Systems"
+description: "Technical system decisions."
+owners: [example-owner]
+---
+
+# Systems

package/examples/basic/systems/runtime.md

@@ -0,0 +1,16 @@
+---
+title: "Runtime baseline"
+owners: [example-owner]
+soft_links:
+  - systems
+---
+
+# Runtime baseline
+
+## Decision
+
+Portable tooling runs on Node.js 22.13 or newer.
+
+## Rationale
+
+A modern baseline keeps filesystem and module behavior consistent.

package/package.json

@@ -1,13 +1,80 @@
 {
   "name": "@first-tree-ai/context-tree",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Portable Context Tree schemas, tooling, and agent skills.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/first-tree-ai/context-tree.git"
+  },
+  "homepage": "https://github.com/first-tree-ai/context-tree#readme",
+  "bugs": {
+    "url": "https://github.com/first-tree-ai/context-tree/issues"
+  },
+  "keywords": [
+    "agents",
+    "context-tree",
+    "knowledge",
+    "memory"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "packageManager": "pnpm@10.12.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "bin": {
+    "context-tree": "./dist/cli/index.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.d.mts",
+      "import": "./dist/schemas.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "skills",
+    "policy",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsdown src/index.ts src/schemas.ts src/cli/index.ts --format esm --dts",
+    "check": "biome check .",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && vitest run",
+    "validate:skills": "vitest run tests/skills.test.ts",
+    "check:package": "pnpm build && publint && attw --pack . --profile esm-only && pnpm package:e2e",
+    "package:e2e": "node scripts/package-e2e.mjs",
+    "check:names": "vitest run tests/names.test.ts",
+    "prepack": "pnpm build && pnpm validate:skills"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "gray-matter": "^4.0.3",
+    "mdast-util-from-markdown": "^2.0.3",
+    "yaml": "^2.8.3",
+    "zod": "^4.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@types/node": "^22.16.0",
+    "publint": "^0.3.16",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  }
 }

package/policy/context-tree-policy.md

@@ -0,0 +1,129 @@
+## Context Tree Policy
+
+### What A Context Tree Is
+
+The Context Tree is durable context, not a source-code mirror, wiki dump, or
+task log. It records current decisions, constraints, ownership, and
+cross-domain relationships with enough rationale that a future reader does
+not have to reconstruct them from GitHub PRs, chat logs, or tribal knowledge.
+
+### Source-System Boundary
+
+The tree records **what was decided and why**; source repos record **how it is
+implemented**. If information would rot when the next refactor lands, it does
+not belong in the tree.
+
+| Belongs in the tree | Stays in the source repo |
+| --- | --- |
+| A choice between alternatives and why the alternatives lost | Function signatures, types, class hierarchies |
+| A constraint that shapes future implementation across repos | Step-by-step implementation walkthroughs |
+| An ownership change or clarified review path | API request / response shapes |
+| A current constraint that resulted from a deprecation | Test fixtures, snapshot data, build / CI config |
+| A new relationship between two domains | Bug fixes that do not change a public contract |
+| Rationale that would not be obvious from the diff alone | Refactors that preserve behaviour |
+| A decision as it stands today: current state + present-tense rationale | Historical narrative of how we got here |
+
+### Content Classes And Authority
+
+- **Normal content** — root/domain `NODE.md` and regular domain leaves. It states current durable truth; when a decision changes, rewrite or remove old claims.
+- **Archive/supporting content** — proposals, meetings, explorations, and raw material such as `raw-context/`. It is evidence, not canonical truth: read it only when asked, when the source is archive/proposal material, or when the task needs archive context. Normal content must not require this class.
+- **Member content** — responsibility, ownership, and review scope such as `members/<id>/NODE.md`. Use it to route or validate *Who*, not as a substitute for normal decision/constraint nodes.
+
+### Code vs Tree Drift Authority
+
+Normal tree content is authoritative for durable context, but not a blind
+override for observed source reality. By default, **code is the ground truth**
+when the tree and code disagree: treat the tree as drifted and update the tree
+from source-backed evidence. `decisionLocksCode: true` reverses that default
+for one node: the tree wins, and code drift escalates to a human owner instead
+of being silently fixed or ignored. Set or rely on that flag only on explicit
+user or host-framework authorization.
+
+### The Double Test
+
+Before writing, apply both questions to every candidate fact:
+
+1. **Decision test.** Does this source establish or change something a future
+   agent must respect when making cross-domain choices?
+2. **Durability test.** If the triggering commit or GitHub PR were rewritten, would
+   the decision still stand?
+
+The candidate belongs in the tree only when both answers are yes. Failing the
+decision test means the source is implementation detail; failing the
+durability test means the source captures how something was done this time,
+not what was decided.
+
+### Content Model: What / Why / Who
+
+- **What** — the decision, design choice, or constraint as it stands today.
+  Write the durable claim, not implementation detail or a timeline of prior
+  states.
+- **Why** — the surviving rationale: constraints that won, alternatives that
+  lost, and design course-corrections translated into present-tense reasoning.
+  Capture **why**, not only what. Design-phase chat, review, and meeting
+  threads are where this rationale is produced: somebody flags a constraint,
+  a first proposal is corrected, or an option conflicts with another domain.
+  The node records the surviving constraint and reasoning from those moments,
+  not the chronology. A node without rationale is a fact, not a decision record.
+- **Who** — ownership, carried by `owners` frontmatter and
+  member content. Do not put ownership in the body, and do not unilaterally
+  edit `owners`.
+
+### Add vs Edit
+
+Default to editing an existing node. A node earns its existence by being
+independently findable, ownable, or linkable; otherwise edit the existing
+node. Add a leaf only when all three hold:
+
+1. **Distinct identity** — a noun-phrase title that does not overlap any
+   sibling.
+2. **Distinct anchor** — at least one of: different `owners`; another domain
+   would `soft_links` to this specific decision; or the source naturally has
+   its own Decision / Rationale / Constraints that cannot co-live with an
+   existing leaf.
+3. **Passes the Double Test.**
+
+Add a directory only when at least three cohesive leaves share an axis. New
+top-level domains require explicit user or host-framework authorization. When
+a decision touches two domains, keep canonical content in the more specific
+domain and link from the broader one with normal-to-normal `soft_links` or
+short prose.
+
+### Node Shape
+
+Required frontmatter:
+
+```yaml
+---
+title: "Short noun phrase"
+owners: [alice, bob]
+---
+```
+
+Useful optional frontmatter: `description`, `soft_links`,
+`lastReviewed`, and `decisionLocksCode`. `lastReviewed` records an actual
+owner review; update it only when that review is the concrete source for a
+source-backed write. Use `owners: ["*"]` only when the user or host framework
+explicitly opens ownership to everyone. Metadata supports scanning, routing,
+and responsibility.
+
+Prefer body sections in this order, omitting any that do not apply:
+`Decision`, `Rationale`, `Constraints`, `Cross-Domain`. There is no
+`Source`, `Provenance`, or `Shipped-in` section; PR, commit, and issue delivery
+history lives in Git history and GitHub PR descriptions, not node prose.
+
+### Write / Verify / GitHub PR Discipline
+
+Default to not writing: a missing node is a question, a noisy node is a trap.
+Source-backed writes require a concrete source artifact and surrounding context
+(source, target, parent, relevant `soft_links`, ownership-adjacent member
+content) unless already known. Actionable future work does not live in normal
+tree content; put it in an issue, source artifact, or authorized decision
+instead. `context-tree verify` must pass before any tree commit. Keep tree prose
+current-state: no timeline, provenance, PR references, or implementation detail.
+Every write starts from a freshly fetched base commit in an isolated clean
+worktree, changes only necessary Markdown, passes verification, and is published
+with a non-force task-branch push and GitHub PR. Never merge automatically. A
+source-backed tree PR stays scoped to one source artifact so owner review and
+rollback stay precise. An invalid base blocks semantic changes; only an explicit
+repair request may produce a repair-only PR limited to validator findings.

package/skills/context-tree-init/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: context-tree-init
+description: Create and publish a new private GitHub-backed Context Tree from an explicit repository identity.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.0"
+---
+
+# Context Tree Init
+
+Create only. Require the user to explicitly provide a GitHub `OWNER/REPO`, empty
+local destination, tree title, and initial owner. Every new repository uses
+`main`; do not accept a configurable branch. Accept only
+`github.com`; GitHub Enterprise Server and other forges are unsupported.
+A Git remote proves identity, not user authority.
+
+First run `context-tree --version`. If the command is missing, stop and tell the
+user to run `npm install --global @first-tree-ai/context-tree`. Never install a
+package automatically.
+
+## Preflight
+
+Before creating a directory, initializing Git, committing, or changing GitHub:
+
+1. Run `context-tree policy` and require `schemaVersion: 1`.
+2. Validate the explicit `OWNER/REPO`, destination, title, and owner. Do not accept a URL in place of `OWNER/REPO`; this avoids credential-bearing repository URLs entirely.
+3. Use the host's existing `git` and `gh` credentials with non-interactive commands. Run `gh auth status` and stop if GitHub access is unavailable. Never request, store, or print credentials.
+4. Confirm that the destination is absent or empty and that `gh repo view "OWNER/REPO"` establishes the target repository does not exist.
+
+## Create and publish
+
+1. Run `context-tree init --repository "OWNER/REPO" --tree-path "<destination>" --title "<title>" --owner "<owner>"`. The scaffold always contains the packaged GitHub Actions workflow pinned to the installed package version and filtered to `main`.
+2. Run `context-tree verify --tree-path "<destination>"` and require a valid result.
+3. Run `git init --initial-branch=main`, add only the scaffolded files, inspect the complete staged diff, and commit. Do not rely on `init.defaultBranch` or other user Git configuration.
+4. Run `gh repo create "OWNER/REPO" --private --source "<destination>" --remote origin --push`. Create a public repository only when the user explicitly requests it; publish `main` only.
+5. Verify that normalized `origin` matches `OWNER/REPO`, the checked-out branch is `main`, the local commit SHA equals `refs/remotes/origin/main`, and `refs/heads/main` exists remotely.
+
+If creation or push has an uncertain result, inspect `gh repo view`, the local
+remote, and `git ls-remote` before retrying only the missing operation. Never
+delete a GitHub repository or overwrite remote history. Stop if the target
+repository already exists or the destination is not absent or empty.

package/skills/context-tree-init/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Init"
+  short_description: "Create a private GitHub Context Tree"
+  default_prompt: "Use $context-tree-init to create and publish this new GitHub-backed Context Tree."

package/skills/context-tree-read/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: context-tree-read
+description: Read task-scoped content from an explicitly authorized GitHub Context Tree checkout.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.0"
+---
+
+# Context Tree Read
+
+Require an explicitly authorized GitHub `OWNER/REPO`, branch, and local
+destination. Never infer authorization from the current directory, a remote, or
+workspace files. A Git remote proves identity, not user authority.
+
+First run `context-tree --version`. If the command is missing, stop and tell the
+user to run `npm install --global @first-tree-ai/context-tree`. Never install a
+package automatically.
+
+## Checkout and freshness
+
+1. Run `context-tree policy` and require `schemaVersion: 1`.
+2. Reject repository URLs as identity input; require canonical `OWNER/REPO`, so credential-bearing URLs cannot enter commands or logs.
+3. If the checkout is absent, clone the explicit branch from `https://github.com/OWNER/REPO.git` with host Git credentials and `GIT_TERMINAL_PROMPT=0`.
+4. Before reusing a checkout, require a clean worktree with `git status --porcelain`, then compare its normalized `origin` and current branch with the explicit inputs. Reject mismatches, detached HEAD, symlinks at the checkout root, and implicit repository discovery.
+5. Run `git pull --ff-only origin "<branch>"`, then record `git rev-parse HEAD`. Do not merge, reset, switch branches, or clean files.
+
+If GitHub is unavailable, stop by default. Continue only when the user
+explicitly authorizes a stale read of this already verified identity and branch.
+Require the worktree to remain clean, label every result `STALE`, report the
+refresh failure, and report the exact local commit SHA. A stale checkout is
+read-only and must never be reused as the starting point for a write.
+
+## Scoped read
+
+1. Run `context-tree read --help`, then `context-tree verify --tree-path "<root>"`.
+2. If verification fails, report the mechanical findings and stop without reading semantic content.
+3. Select narrowly with `context-tree read --tree-path "<root>" [path] --pattern "<glob>" --depth <n> --content`.
+4. Start with the root and relevant parents, then matched leaves and normal `soft_links` targets. Request member or archive-supporting classes only when required.
+5. Apply the packaged policy when code and tree content conflict, and include the recorded Git commit SHA with the result.
+
+The CLI performs no Git or GitHub operations. Keep the result task-scoped.

package/skills/context-tree-read/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Read"
+  short_description: "Read relevant Context Tree decisions safely"
+  default_prompt: "Use $context-tree-read to read the relevant decisions from this explicitly supplied Context Tree."

package/skills/context-tree-write/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: context-tree-write
+description: Publish a source-backed Context Tree change through an isolated GitHub pull request.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.0"
+---
+
+# Context Tree Write
+
+Require a concrete source artifact plus an explicitly authorized GitHub
+`OWNER/REPO` and base branch. Accept a PR, issue, commit discussion, decision
+document, meeting note, or pasted source. Without concrete evidence, stop.
+A Git remote proves identity, not user authority.
+
+First run `context-tree --version`. If the command is missing, stop and tell the
+user to run `npm install --global @first-tree-ai/context-tree`. Never install a
+package automatically.
+
+Apply both durability tests: the source must establish something future agents
+must respect, and it must remain true if the triggering implementation is
+rewritten. Otherwise leave the tree unchanged.
+
+## Fresh isolated base
+
+1. Run `context-tree policy` and require `schemaVersion: 1`.
+2. Require canonical `OWNER/REPO`, not a repository URL, and use existing host `git` and `gh` credentials with `GIT_TERMINAL_PROMPT=0`.
+3. Verify any management checkout's normalized `origin`. Fetch the explicit base branch and resolve `refs/remotes/origin/<base>` to its exact Git commit SHA. A stale checkout may not become a write.
+4. Create a unique task branch and agent-owned isolated worktree at that exact fetched commit. Never edit the shared checkout.
+5. Require `git status --porcelain` to be empty and run `context-tree verify --tree-path "<root>"` before reading semantic content.
+
+If the base is invalid, block all semantic edits. Continue only for an explicit
+repair request, and make a repair-only PR whose changes are limited to exact
+validator findings supported by existing authorized evidence. Never invent
+owners, decisions, structure, or business content. The complete repaired tree
+must pass verification before publication.
+
+## Source-backed edit
+
+1. Read the source and the minimum target, parent, relationship, and ownership context with `context-tree read --content`.
+2. Prefer an existing node. Require explicit authority for ownership changes, locked decisions, or a new top-level domain.
+3. Edit only the necessary regular, non-symlink Markdown files directly in the isolated worktree. Preserve path containment and never replace or traverse symlinks.
+4. Run `context-tree verify --tree-path "<root>"` on the final tree.
+5. Inspect the complete `git diff`, including every changed path and full patch. Stop if it contains anything outside the authorized Context Tree change.
+
+## GitHub publication
+
+1. Run repository-prescribed checks relevant to the changed tree.
+2. Commit the verified diff on the task branch.
+3. Push with `git push --set-upstream origin "<task-branch>"`. Use a non-force push; never force push or push directly to the base branch.
+4. Open a GitHub PR targeting the explicit base with `gh pr create --base "<base>" --head "<task-branch>"`. Never merge automatically and never request reviewers automatically.
+
+If push or PR creation has an unknown result, inspect the remote branch and
+existing PRs before retrying only a missing operation. Leave conflicts and
+outdated-branch handling to GitHub. Keep one coherent source per change and
+remove an agent-owned worktree only when it is clean; never remove a pre-existing
+or dirty worktree.

package/skills/context-tree-write/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Write"
+  short_description: "Apply source-backed Context Tree updates"
+  default_prompt: "Use $context-tree-write to reflect this concrete source artifact into the Context Tree."

package/templates/member-node.md

@@ -0,0 +1,13 @@
+---
+title: {{ownerJson}}
+description: "Initial Context Tree owner."
+owners: [{{ownerJson}}]
+type: human
+role: "Context Tree owner"
+domains:
+  - "context-tree"
+---
+
+# {{owner}}
+
+Owns the initial Context Tree structure and reviews changes until responsibility is delegated explicitly.

package/templates/members-index.md

@@ -0,0 +1,9 @@
+---
+title: "Members"
+description: "Member definitions and work specifications."
+owners: [{{ownerJson}}]
+---
+
+# Members
+
+Member definitions, work scope, and review responsibilities.

package/templates/root-node.md

@@ -0,0 +1,15 @@
+---
+title: {{titleJson}}
+description: "Durable decisions, constraints, ownership, and cross-domain relationships."
+owners: [{{ownerJson}}]
+---
+
+# {{title}}
+
+## Decision
+
+This Context Tree is the canonical home for durable context within its declared scope.
+
+## Rationale
+
+Keeping current decisions and their surviving rationale together lets future readers act without reconstructing history.

package/templates/scope.md

@@ -0,0 +1,5 @@
+---
+schemaVersion: 1
+---
+
+This Context Tree covers the durable decisions, constraints, ownership, and cross-domain relationships maintained by {{title}}.

package/templates/validate-context-tree.yml

@@ -0,0 +1,16 @@
+name: Validate Context Tree
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Validate Context Tree
+        run: npx --yes @first-tree-ai/context-tree@{{packageVersion}} verify --tree-path .