first-tree 0.0.2 → 0.0.4

package/skills/first-tree/references/source-map.md

@@ -0,0 +1,94 @@
+# Context Tree Source Map
+
+This is the canonical reading index for the single-skill architecture. If a
+maintainer needs information to safely change the framework or thin CLI, that
+information should be discoverable from this file.
+
+## Read First
+
+| Path | Why it matters |
+| --- | --- |
+| `SKILL.md` | Trigger conditions, workflow, and validation contract |
+| `references/about.md` | Product framing for what Context Tree is and is not |
+| `references/onboarding.md` | The onboarding narrative that `help onboarding` and `init` surface |
+| `references/principles.md` | Decision-model reference |
+| `references/ownership-and-naming.md` | Ownership contract |
+| `references/upgrade-contract.md` | Installed layout and upgrade semantics |
+| `references/maintainer-architecture.md` | Source-repo architecture and invariants |
+| `references/maintainer-thin-cli.md` | Root shell contract and anti-duplication rules |
+| `references/maintainer-build-and-distribution.md` | Build, pack, and distribution contract |
+| `references/maintainer-testing.md` | Test workflow and maintainer validation expectations |
+
+## Runtime Payload
+
+The installed skill payload lives under `assets/framework/`.
+
+| Path | Purpose |
+| --- | --- |
+| `assets/framework/manifest.json` | Runtime asset contract |
+| `assets/framework/VERSION` | Version marker for installed payloads |
+| `assets/framework/templates/` | Generated scaffolds |
+| `assets/framework/workflows/` | CI templates |
+| `assets/framework/prompts/` | Review prompt payload |
+| `assets/framework/examples/` | Agent integration examples |
+| `assets/framework/helpers/` | Shipped helper scripts and TypeScript utilities |
+| `progress.md` | Generated in user repos to track unfinished setup or upgrade tasks |
+
+## Framework Engine Surface
+
+These skill-owned files implement the framework behavior.
+
+| Path | Purpose |
+| --- | --- |
+| `engine/commands/` | Stable command entrypoints that the thin CLI imports |
+| `engine/init.ts` / `engine/verify.ts` / `engine/upgrade.ts` | Command implementations for install, verify, and upgrade |
+| `engine/onboarding.ts` | Canonical onboarding text loader |
+| `engine/repo.ts` | Repo inspection, source-vs-tree heuristics, and worktree-aware git-root helpers |
+| `engine/rules/` | Situation-aware task generation after `init` |
+| `engine/validators/` | Deterministic tree and member validation |
+| `engine/runtime/asset-loader.ts` | Path constants plus legacy-layout detection |
+| `engine/runtime/installer.ts` | Bundled-package discovery, skill copy, and template-render helpers |
+| `engine/runtime/upgrader.ts` | Packaged-skill version comparison helpers |
+| `engine/runtime/adapters.ts` | Agent-integration path helpers |
+
+## Thin CLI Shell Surface
+
+These root files are distribution shell code. They should stay thin and should
+not become the only place important maintainer knowledge lives.
+
+| Path | Purpose |
+| --- | --- |
+| `src/cli.ts` | Thin command parser and dispatcher |
+| `src/md.d.ts` | Build-time markdown module typing |
+| `package.json` | Package metadata, import aliases, and scripts |
+| `tsconfig.json` | TypeScript compile boundaries |
+| `tsdown.config.ts` | Build entry and asset handling |
+| `vitest.config.ts` | Unit-test entrypoints |
+| `.github/workflows/ci.yml` | Thin CI shell |
+| `README.md` | Thin distribution overview |
+| `AGENTS.md` | Thin maintainer pointer for agent sessions |
+
+## Validation
+
+| Path | Coverage |
+| --- | --- |
+| `tests/init.test.ts` | Init scaffolding behavior |
+| `tests/verify.test.ts` | Verification and progress gating |
+| `tests/rules.test.ts` | Task generation text |
+| `tests/asset-loader.test.ts` | Layout detection and path precedence |
+| `tests/generate-codeowners.test.ts` | Ownership helper behavior |
+| `tests/run-review.test.ts` | Review helper behavior |
+| `tests/skill-artifacts.test.ts` | Skill export and documentation integrity |
+| `tests/thin-cli.test.ts` | Thin CLI entrypoint smoke coverage |
+| `tests/upgrade.test.ts` | Installed-skill upgrade behavior |
+
+## Compatibility Notes
+
+- The source repo intentionally contains no root `.context-tree/`, `docs/`,
+  mirror skills, or bundled repo snapshot.
+- Legacy `.context-tree/...` paths still matter only for migrating existing
+  user repos; the compatibility logic lives in
+  `engine/runtime/asset-loader.ts` and `engine/upgrade.ts`.
+- Root `README.md` and `AGENTS.md` are intentionally brief. Important
+  information must live in the skill references instead.
+- If you change `references/` or `assets/framework/`, run `pnpm validate:skill`.

package/skills/first-tree/references/upgrade-contract.md

@@ -0,0 +1,94 @@
+# Upgrade Contract
+
+This file describes the current installed-layout contract and the compatibility
+rules we keep for legacy `skills/first-tree-cli-framework/` and
+`.context-tree/` repos.
+
+## Canonical Source
+
+- `skills/first-tree/` is the only source of truth.
+- `references/` contains explanatory material.
+- `assets/framework/` contains the shipped runtime payload.
+- The distributable `first-tree` package must carry the canonical skill inside
+  the package itself.
+- The source repo does not keep a root `.context-tree/`, `docs/`, mirror skill
+  directories, or a bundled repo snapshot.
+
+## Installed Layout
+
+The current installed layout in a user repo is:
+
+```text
+skills/
+  first-tree/
+    SKILL.md
+    progress.md
+    references/
+    assets/
+      framework/
+        manifest.json
+        VERSION
+        templates/
+        workflows/
+        prompts/
+        examples/
+        helpers/
+```
+
+The tree content still lives outside the skill:
+
+- `NODE.md`
+- `AGENTS.md`
+- `members/`
+
+## Command Intent
+
+- `context-tree init`
+  - when run in a source/workspace repo, creates or reuses a sibling dedicated
+    tree repo by default
+  - installs the skill into the target tree repo
+  - renders top-level tree scaffolding from the skill templates
+  - writes progress state to `skills/first-tree/progress.md`
+- `context-tree verify`
+  - checks progress state from the installed skill
+  - validates root/frontmatter/agent markers
+  - runs node and member validators
+- `context-tree upgrade`
+  - compares the installed skill payload version to the skill bundled with the
+    currently running `first-tree` package
+  - refreshes the installed skill payload without overwriting tree content
+  - migrates repos that still use the previous
+    `skills/first-tree-cli-framework/` path onto `skills/first-tree/`
+  - migrates legacy `.context-tree/` repos onto the installed skill layout
+  - preserves user-authored sections such as the editable part of `AGENTS.md`
+
+## Compatibility Rules For Legacy Trees
+
+- `context-tree init` never creates a new `.context-tree/`.
+- `context-tree init --here` preserves the explicit in-place bootstrap path for
+  already-created tree repos.
+- Default dedicated-tree-repo creation is local-only. The CLI may create a new
+  sibling git repo on disk, but it must not clone the source repo or depend on
+  network access.
+- Normal `context-tree init` and `context-tree upgrade` flows do not clone the
+  source repo or require network access.
+- `context-tree verify` may still read a legacy
+  `skills/first-tree-cli-framework/...` or `.context-tree/...` layout in an
+  existing user repo so the repo can be upgraded in place.
+- `context-tree upgrade` must migrate either legacy layout onto
+  `skills/first-tree/` and remove the old directory afterward.
+- When both layouts are present, prefer the installed skill layout.
+- Existing repos may still have a legacy `AGENT.md`; `init` and `upgrade`
+  must not silently overwrite it, and follow-up tasks should direct users to
+  rename it to `AGENTS.md`.
+
+## Invariants
+
+- Templates, workflows, prompts, helper scripts, and explanatory references
+  must stay aligned.
+- If a change affects installed payload contents, bump
+  `assets/framework/VERSION` so packaged upgrades can detect it.
+- Ownership behavior must stay identical across layout changes.
+- The tree remains decision-focused; execution detail stays in source systems.
+- A path migration is incomplete if task text, docs, tests, and runtime assets
+  disagree about where the framework lives.

package/skills/first-tree/scripts/check-skill-sync.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+find_repo_root() {
+  local dir="$SKILL_DIR"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]] && grep -q '"name": "first-tree"' "$dir/package.json"; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+require_file() {
+  local path="$1"
+  if [[ ! -f "$path" ]]; then
+    echo "Missing file: $path" >&2
+    exit 1
+  fi
+}
+
+REPO_ROOT="$(find_repo_root || true)"
+SOURCE_DIR=""
+if [[ -n "$REPO_ROOT" ]]; then
+  SOURCE_DIR="$REPO_ROOT/skills/first-tree"
+fi
+
+if [[ -z "$REPO_ROOT" || "$SKILL_DIR" != "$SOURCE_DIR" ]]; then
+  echo "Run this script from the source-of-truth skill at skills/first-tree inside a live first-tree checkout." >&2
+  exit 1
+fi
+
+require_file "$SOURCE_DIR/SKILL.md"
+require_file "$SOURCE_DIR/agents/openai.yaml"
+require_file "$SOURCE_DIR/references/about.md"
+require_file "$SOURCE_DIR/references/onboarding.md"
+require_file "$SOURCE_DIR/references/principles.md"
+require_file "$SOURCE_DIR/references/ownership-and-naming.md"
+require_file "$SOURCE_DIR/references/source-map.md"
+require_file "$SOURCE_DIR/references/upgrade-contract.md"
+require_file "$SOURCE_DIR/references/maintainer-architecture.md"
+require_file "$SOURCE_DIR/references/maintainer-thin-cli.md"
+require_file "$SOURCE_DIR/references/maintainer-build-and-distribution.md"
+require_file "$SOURCE_DIR/references/maintainer-testing.md"
+require_file "$SOURCE_DIR/engine/init.ts"
+require_file "$SOURCE_DIR/engine/onboarding.ts"
+require_file "$SOURCE_DIR/engine/repo.ts"
+require_file "$SOURCE_DIR/engine/upgrade.ts"
+require_file "$SOURCE_DIR/engine/verify.ts"
+require_file "$SOURCE_DIR/engine/commands/help.ts"
+require_file "$SOURCE_DIR/engine/commands/init.ts"
+require_file "$SOURCE_DIR/engine/commands/upgrade.ts"
+require_file "$SOURCE_DIR/engine/commands/verify.ts"
+require_file "$SOURCE_DIR/engine/rules/index.ts"
+require_file "$SOURCE_DIR/engine/runtime/asset-loader.ts"
+require_file "$SOURCE_DIR/engine/runtime/installer.ts"
+require_file "$SOURCE_DIR/engine/runtime/upgrader.ts"
+require_file "$SOURCE_DIR/engine/runtime/adapters.ts"
+require_file "$SOURCE_DIR/engine/validators/members.ts"
+require_file "$SOURCE_DIR/engine/validators/nodes.ts"
+require_file "$SOURCE_DIR/tests/init.test.ts"
+require_file "$SOURCE_DIR/tests/verify.test.ts"
+require_file "$SOURCE_DIR/tests/skill-artifacts.test.ts"
+require_file "$SOURCE_DIR/assets/framework/manifest.json"
+require_file "$SOURCE_DIR/assets/framework/VERSION"
+require_file "$SOURCE_DIR/assets/framework/prompts/pr-review.md"
+require_file "$SOURCE_DIR/assets/framework/templates/root-node.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/agents.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/members-domain.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/member-node.md.template"
+require_file "$SOURCE_DIR/assets/framework/workflows/validate.yml"
+require_file "$SOURCE_DIR/assets/framework/workflows/pr-review.yml"
+require_file "$SOURCE_DIR/assets/framework/workflows/codeowners.yml"
+require_file "$SOURCE_DIR/assets/framework/examples/claude-code/README.md"
+require_file "$SOURCE_DIR/assets/framework/examples/claude-code/settings.json"
+require_file "$SOURCE_DIR/assets/framework/helpers/generate-codeowners.ts"
+require_file "$SOURCE_DIR/assets/framework/helpers/run-review.ts"
+require_file "$SOURCE_DIR/assets/framework/helpers/inject-tree-context.sh"
+
+# Check for legacy artifacts that should not be committed.
+# Use git ls-files to ignore untracked local files (e.g. .claude/settings.local.json).
+for legacy_path in \
+  ".agents" \
+  ".claude" \
+  ".context-tree" \
+  "docs" \
+  "skills/first-tree-cli-framework" \
+  "tests" \
+  "skills/first-tree/references/repo-snapshot"
+do
+  if git -C "$REPO_ROOT" ls-files --error-unmatch "$legacy_path" >/dev/null 2>&1; then
+    echo "Unexpected legacy artifact tracked in git: $legacy_path" >&2
+    exit 1
+  fi
+done
+
+if [[ -e "$SOURCE_DIR/evals" ]]; then
+  echo "Skill should not contain repo-only eval tooling." >&2
+  exit 1
+fi
+
+require_file "$REPO_ROOT/evals/context-tree-eval.test.ts"
+require_file "$REPO_ROOT/evals/README.md"
+require_file "$REPO_ROOT/evals/helpers/case-loader.ts"
+require_file "$REPO_ROOT/evals/scripts/tree-manager.ts"
+require_file "$REPO_ROOT/evals/tests/eval-helpers.test.ts"
+
+if grep -q '"#docs/\*"' "$REPO_ROOT/package.json"; then
+  echo "package.json still exposes the legacy #docs import alias." >&2
+  exit 1
+fi
+
+if ! grep -q '"#skill/\*"' "$REPO_ROOT/package.json"; then
+  echo "package.json is missing the canonical #skill import alias." >&2
+  exit 1
+fi
+
+if ! grep -q '"skills/first-tree"' "$REPO_ROOT/package.json"; then
+  echo "package.json is missing the canonical skill in the published files list." >&2
+  exit 1
+fi
+
+if ! grep -q '#skill/engine/commands/init.js' "$REPO_ROOT/src/cli.ts"; then
+  echo "src/cli.ts is not dispatching to the skill-owned engine." >&2
+  exit 1
+fi
+
+echo "Canonical skill structure is clean."

package/skills/first-tree/scripts/quick_validate.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Portable quick validator for a skill directory.
+
+This version is intentionally self-contained so it can run in CI and in copied
+skill folders without depending on external Python packages.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def extract_frontmatter(text: str) -> tuple[bool, str]:
+    if not text.startswith("---\n"):
+        return False, "No YAML frontmatter found"
+    match = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+    return True, match.group(1)
+
+
+def parse_simple_frontmatter(frontmatter: str) -> dict[str, str]:
+    data: dict[str, str] = {}
+    for line in frontmatter.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if ":" not in stripped:
+            continue
+        key, value = stripped.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if value.startswith(("'", '"')) and value.endswith(("'", '"')) and len(value) >= 2:
+            value = value[1:-1]
+        data[key] = value
+    return data
+
+
+def validate_skill(skill_path: str) -> tuple[bool, str]:
+    skill_dir = Path(skill_path)
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+    ok, frontmatter_or_error = extract_frontmatter(content)
+    if not ok:
+        return False, frontmatter_or_error
+
+    frontmatter = parse_simple_frontmatter(frontmatter_or_error)
+
+    unexpected = set(frontmatter.keys()) - {"name", "description"}
+    if unexpected:
+      return False, f"Unexpected key(s) in frontmatter: {', '.join(sorted(unexpected))}"
+
+    name = frontmatter.get("name", "").strip()
+    if not name:
+        return False, "Missing 'name' in frontmatter"
+    if not re.match(r"^[a-z0-9-]+$", name):
+        return False, f"Name '{name}' should be hyphen-case"
+    if name.startswith("-") or name.endswith("-") or "--" in name:
+        return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        return False, f"Name is too long ({len(name)} > {MAX_SKILL_NAME_LENGTH})"
+
+    description = frontmatter.get("description", "").strip()
+    if not description:
+        return False, "Missing 'description' in frontmatter"
+    if len(description) > 1024:
+        return False, f"Description is too long ({len(description)} > 1024)"
+
+    openai_yaml = skill_dir / "agents" / "openai.yaml"
+    if not openai_yaml.exists():
+        return False, "agents/openai.yaml not found"
+
+    return True, "Skill is valid!"
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: quick_validate.py <skill_directory>")
+        return 1
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    return 0 if valid else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/first-tree/scripts/run-local-cli.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+INSTALL_GUIDE="${SKILL_DIR}/references/onboarding.md"
+
+find_repo_root() {
+  local dir="$SKILL_DIR"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]] && grep -q '"name": "first-tree"' "$dir/package.json"; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+REPO_ROOT="$(find_repo_root || true)"
+
+if [[ -n "${REPO_ROOT}" ]]; then
+  cd "$REPO_ROOT"
+  pnpm build >/dev/null
+  exec node dist/cli.js "$@"
+fi
+
+if command -v context-tree >/dev/null 2>&1; then
+  exec context-tree "$@"
+fi
+
+echo "Could not find a live first-tree checkout or a 'context-tree' binary on PATH." >&2
+echo "Install the npm package 'first-tree' if you want the portable runner to invoke the CLI outside the repo." >&2
+echo "Read the onboarding guide at: ${INSTALL_GUIDE}" >&2
+exit 1

package/skills/first-tree/tests/asset-loader.test.ts

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
+  LEGACY_PROGRESS,
+  LEGACY_VERSION,
+  detectFrameworkLayout,
+  frameworkVersionCandidates,
+  progressFileCandidates,
+  resolveFirstExistingPath,
+} from "#skill/engine/runtime/asset-loader.js";
+import { useTmpDir } from "./helpers.js";
+
+describe("asset-loader", () => {
+  it("prefers the installed skill layout when both layouts exist", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, "skills", "first-tree", "assets", "framework"), {
+      recursive: true,
+    });
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, FRAMEWORK_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("skill");
+    expect(resolveFirstExistingPath(tmp.path, [FRAMEWORK_VERSION, LEGACY_VERSION])).toBe(
+      FRAMEWORK_VERSION,
+    );
+  });
+
+  it("falls back to the legacy layout when the skill is not installed", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy");
+  });
+
+  it("detects the previous installed skill name before the .context-tree layout", () => {
+    const tmp = useTmpDir();
+    mkdirSync(
+      join(tmp.path, "skills", "first-tree-cli-framework", "assets", "framework"),
+      {
+        recursive: true,
+      },
+    );
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_SKILL_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-skill");
+    expect(
+      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
+    ).toBe(LEGACY_SKILL_VERSION);
+  });
+
+  it("prefers the installed progress file candidate", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
+    mkdirSync(join(tmp.path, "skills", "first-tree-cli-framework"), {
+      recursive: true,
+    });
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "new");
+    writeFileSync(join(tmp.path, LEGACY_SKILL_PROGRESS), "old-skill");
+    writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");
+
+    expect(resolveFirstExistingPath(tmp.path, progressFileCandidates())).toBe(
+      INSTALLED_PROGRESS,
+    );
+  });
+});

package/skills/first-tree/tests/generate-codeowners.test.ts

@@ -0,0 +1,94 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  parseOwners,
+  resolveNodeOwners,
+  collectEntries,
+  formatOwners,
+} from "../assets/framework/helpers/generate-codeowners.js";
+import { useTmpDir } from "./helpers.js";
+
+function write(root: string, relPath: string, content: string): string {
+  const p = join(root, relPath);
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, content);
+  return p;
+}
+
+// --- parseOwners ---
+
+describe("parseOwners", () => {
+  it("parses valid owners", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: [alice, bob]\n---\n");
+    expect(parseOwners(p)).toEqual(["alice", "bob"]);
+  });
+
+  it("handles empty owners", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: []\n---\n");
+    expect(parseOwners(p)).toEqual([]);
+  });
+
+  it("handles wildcard", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: [*]\n---\n");
+    expect(parseOwners(p)).toEqual(["*"]);
+  });
+
+  it("returns null for no frontmatter", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "# Just a heading\n");
+    expect(parseOwners(p)).toBeNull();
+  });
+});
+
+// --- resolveNodeOwners ---
+
+describe("resolveNodeOwners", () => {
+  it("returns direct owners", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root-owner]\n---\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: [domain-owner]\n---\n");
+    const cache = new Map<string, string[]>();
+    const result = resolveNodeOwners(join(tmp.path, "domain"), tmp.path, cache);
+    expect(result).toEqual(["domain-owner"]);
+  });
+
+  it("inherits from parent", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root-owner]\n---\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: []\n---\n");
+    const cache = new Map<string, string[]>();
+    const result = resolveNodeOwners(join(tmp.path, "domain"), tmp.path, cache);
+    expect(result).toEqual(["root-owner"]);
+  });
+});
+
+// --- collectEntries ---
+
+describe("collectEntries", () => {
+  it("excludes dot-prefixed dirs", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root]\n---\n# Root\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: [alice]\n---\n# Domain\n");
+    write(tmp.path, ".hidden/NODE.md", "---\nowners: [secret]\n---\n# Hidden\n");
+    const entries = collectEntries(tmp.path);
+    const patterns = entries.map(([pat]) => pat);
+    expect(patterns.some((p) => p.includes("domain"))).toBe(true);
+    expect(patterns.some((p) => p.includes(".hidden"))).toBe(false);
+  });
+});
+
+// --- formatOwners ---
+
+describe("formatOwners", () => {
+  it("deduplicates owners", () => {
+    expect(formatOwners(["alice", "bob", "alice"])).toBe("@alice @bob");
+  });
+
+  it("adds @ prefix", () => {
+    expect(formatOwners(["alice"])).toBe("@alice");
+  });
+});