From c5bada5e6bfefdb2dc0ae91c4e59e84ed7d6dc28 Mon Sep 17 00:00:00 2001 From: Ryan Lee Date: Sun, 30 Aug 2026 04:45:18 +0000 Subject: [PATCH] chore(harness): bootstrap project harness and doctrine mirroring systemfsoftware --- .codegraph/.gitignore | 5 ++++ AGENTS.md | 64 ++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 3 ++ CONSTITUTION-ARTICLES.md | 1 + CONSTITUTION.md | 1 + 5 files changed, 74 insertions(+) create mode 100644 .codegraph/.gitignore create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 120000 CONSTITUTION-ARTICLES.md create mode 120000 CONSTITUTION.md diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore new file mode 100644 index 0000000..d20c0fe --- /dev/null +++ b/.codegraph/.gitignore @@ -0,0 +1,5 @@ +# CodeGraph data files — local to each machine, not for committing. +# Ignore everything in .codegraph/ except this file itself, so transient +# files (the database, daemon.pid, sockets, logs) never show up in git. +* +!.gitignore diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..54847f5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,64 @@ +# AGENTS.md — Worktrunk Scripts + +Deno worktree hooks for `worktrunk` automating environment setup, warm-copy indexing, and path isolation. + +## Standing Law + +Read `CONSTITUTION.md` before architecture or rule authoring. + +Startup: confirm working directory and active task; run `deno task check` and repair failures before adding scope. + +## Routing + +Load docs on-demand when triggers fire; do not perform eager multi-spec reads at startup. + +| Doc | Trigger | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `CONSTITUTION.md` | architecture changes, rule authoring, or design disputes | +| `CONSTITUTION-ARTICLES.md` | editing source files (pure core, types, boundaries, testing) | +| `docs/solutions/tooling/bash-to-deno-port-semantics.md` | modifying path mapping, git command wrappers, or cross-platform Deno CLI semantics | +| `subtrees.toml` | updating or adding vendored git subtrees | + +## Stack & Conventions + +- Deno 2.x (`deno task check`, `deno task test`). +- Hook scripts under `scripts/` are standalone CLIs (no exports). +- Shared utilities live under `scripts/lib/`. +- Lint via `deno lint`; formatting via `dprint`. Gate: `deno task check`. + +## Surface Classes + +| Surface | Examples | Rule | +| ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- | +| **Evaluator** | `.github/workflows/` | Its own commit, never shared with the work it judges; gate observed red before and green after. | +| **Doctrine** | `CONSTITUTION.md`, `AGENTS.md`, `docs/` | Editable, but never an input to a gate. | +| **Editable** | `scripts/`, `deno.json`, `dprint.json` | Edit freely within active task. | + +## Directory Map + +Root doctrine files `CONSTITUTION.md`, `CONSTITUTION-ARTICLES.md`. + +| Directory | What it is | Governance | +| -------------- | --------------------------------------------------------- | ----------------- | +| `scripts/` | Standalone lifecycle CLI entrypoints invoked by worktrunk | Root | +| `scripts/lib/` | Shared git, path, and filesystem utilities | Root | +| `repos/` | Vendored third-party trees (`subtrees.toml`), read-only | `WT-S3` read-only | +| `docs/` | Solutions, plans, and technical documentation | Editable | + +## Rules — Must Hold At Done + +Every row is load-bearing and names its runnable gate. + +| ID | Rule | Gate | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| **WT-S3** | `repos/` is a vendored third-party reference subtree; never edit it. | `review — git status check` | +| **WT-R1** | Hook scripts in `scripts/` must declare explicit Deno permission shebangs (`#!/usr/bin/env -S deno run --allow-...`) and avoid `-A`/`--allow-all`. | `deno task check` | +| **WT-R2** | Shared utilities belong in `scripts/lib/`; hook entrypoints under `scripts/` are standalone CLIs with no exports. | `deno task check` | +| **WT-R3** | Code formatting and linting pass with zero diagnostics. | `deno task check` | +| **WT-C1** | `type(scope): subject` with no trailing period. Keep subjects concise. | `review — commit message inspection` | + +## Verification Commands + +```bash +deno task check +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..58bc96f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +@AGENTS.md +@subtrees.toml +@CONSTITUTION.md diff --git a/CONSTITUTION-ARTICLES.md b/CONSTITUTION-ARTICLES.md new file mode 120000 index 0000000..5f15994 --- /dev/null +++ b/CONSTITUTION-ARTICLES.md @@ -0,0 +1 @@ +repos/constitution/CONSTITUTION-ARTICLES.md \ No newline at end of file diff --git a/CONSTITUTION.md b/CONSTITUTION.md new file mode 120000 index 0000000..67e49c5 --- /dev/null +++ b/CONSTITUTION.md @@ -0,0 +1 @@ +repos/constitution/CONSTITUTION.md \ No newline at end of file