Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Harness tree: the harness as one value

Rach Pradhan5d0122d981ad
diff --git a/src/args.zig b/src/args.zig
index 38e64891..023cc539 100644
--- a/src/args.zig
+++ b/src/args.zig
@@ -121,7 +121,7 @@ pub fn parse(init: std.process.Init) !Flags {
_ = it.next(); // argv[0]
while (it.next()) |arg| {
if (flags.positionals.items.len > 0 and
- (std.mem.eql(u8, flags.positionals.items[0], "mcp") or std.mem.eql(u8, flags.positionals.items[0], "learn") or std.mem.eql(u8, flags.positionals.items[0], "peer") or std.mem.eql(u8, flags.positionals.items[0], "keys")))
+ (std.mem.eql(u8, flags.positionals.items[0], "mcp") or std.mem.eql(u8, flags.positionals.items[0], "learn") or std.mem.eql(u8, flags.positionals.items[0], "peer") or std.mem.eql(u8, flags.positionals.items[0], "keys") or std.mem.eql(u8, flags.positionals.items[0], "harness-tree")))
{
try flags.positionals.append(arena, try arena.dupe(u8, arg));
} else if (std.mem.startsWith(u8, arg, "-")) {
@@ -286,7 +286,7 @@ pub fn parse(init: std.process.Init) !Flags {
flags.is_subcommand = flags.positionals.items.len > 0 and
(std.mem.eql(u8, flags.positionals.items[0], "login") or std.mem.eql(u8, flags.positionals.items[0], "logout") or std.mem.eql(u8, flags.positionals.items[0], "key") or std.mem.eql(u8, flags.positionals.items[0], "mcp") or std.mem.eql(u8, flags.positionals.items[0], "learn") or
std.mem.eql(u8, flags.positionals.items[0], "serve") or std.mem.eql(u8, flags.positionals.items[0], "update") or std.mem.eql(u8, flags.positionals.items[0], "title") or std.mem.eql(u8, flags.positionals.items[0], "repl") or (!flags.print_flag and std.mem.eql(u8, flags.positionals.items[0], "tui")) or
- std.mem.eql(u8, flags.positionals.items[0], "worktree") or std.mem.eql(u8, flags.positionals.items[0], "sandboxes") or std.mem.eql(u8, flags.positionals.items[0], "cube") or std.mem.eql(u8, flags.positionals.items[0], "models") or
+ std.mem.eql(u8, flags.positionals.items[0], "worktree") or std.mem.eql(u8, flags.positionals.items[0], "harness-tree") or std.mem.eql(u8, flags.positionals.items[0], "sandboxes") or std.mem.eql(u8, flags.positionals.items[0], "cube") or std.mem.eql(u8, flags.positionals.items[0], "models") or
std.mem.eql(u8, flags.positionals.items[0], "remote-control") or std.mem.eql(u8, flags.positionals.items[0], "remote") or @import("acp.zig").isAcpSubcommand(flags.positionals.items[0])); // `acp` also arms ACP's stdout discipline (json_mode) — see acp.isAcpSubcommand
if (!flags.is_subcommand and flags.positionals.items.len > 0) {
flags.oneshot_prompt = try std.mem.join(arena, " ", flags.positionals.items);
diff --git a/src/harness_tree.zig b/src/harness_tree.zig
new file mode 100644
index 00000000..dd5c4a3c
--- /dev/null
+++ b/src/harness_tree.zig
@@ -0,0 +1,327 @@
+//! The harness as one value: every file graff reads to decide HOW it works
+//! (not what it works on), loaded from one checkout, written into another,
+//! and digested. This is the editable surface of a refine loop (propose →
+//! probe → compose): a proposer edits a Tree, harness_tree_check turns a bad
+//! edit into prose the proposer can fix, a probe runs graff in a checkout the
+//! Tree was written into, and the digest names a setup the way prompt_sha
+//! names a persona.
+//!
+//! The eight parts map onto files graff already loads:
+//!
+//! system prompt, guardrails, the instruction file: the first non-empty
+//! memory, tool guidance → one of hot_context.instruction_names
+//! skills → .agents/skills/<name>/SKILL.md (+ files
+//! beside it) or .agents/skills/<name>.md
+//! subagents → .harness/agents/<name>.md | .toml
+//! scripts → .harness/scripts/<file>
+//! plugins → the "hooks" object of .harness/settings.json
+//!
+//! Anything else under those directories is off the surface: load skips it and
+//! write never touches it. The hooks file holds only the hooks object; write
+//! merges it into the destination's settings and leaves other keys alone.
+
+const std = @import("std");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+
+pub const instruction_names = @import("hot_context.zig").instruction_names;
+pub const skills_dir = ".agents/skills";
+pub const agents_dir = ".harness/agents";
+pub const scripts_dir = ".harness/scripts";
+pub const hooks_path = @import("harness_policy.zig").settings_path;
+
+pub const max_file_bytes: usize = 256 * 1024;
+pub const max_files: usize = 128;
+/// Directory levels allowed below a skill's own directory (scripts/x.py).
+const skill_depth: usize = 2;
+
+pub const Part = enum {
+ instructions,
+ skill,
+ skill_file,
+ subagent,
+ script,
+ hooks,
+
+ pub fn label(p: Part) []const u8 {
+ return switch (p) {
+ .instructions => "instructions",
+ .skill => "skill",
+ .skill_file => "skill file",
+ .subagent => "subagent",
+ .script => "script",
+ .hooks => "hooks",
+ };
+ }
+};
+
+pub const File = struct { path: []const u8, data: []const u8 };
+
+/// Files sorted by path, each path unique and on the surface.
+pub const Tree = struct {
+ files: []const File = &.{},
+
+ pub fn get(self: Tree, path: []const u8) ?[]const u8 {
+ for (self.files) |f| if (std.mem.eql(u8, f.path, path)) return f.data;
+ return null;
+ }
+
+ pub fn instructions(self: Tree) ?File {
+ for (self.files) |f| if (classify(f.path) == .instructions) return f;
+ return null;
+ }
+};
+
+/// A loaded tree plus the paths under the surface directories that load left
+/// out (off-surface names, oversize files), so a caller can say so.
+pub const Loaded = struct { tree: Tree, skipped: []const []const u8 };
+
+/// Which part of the harness `path` is, or null when it is off the surface.
+pub fn classify(path: []const u8) ?Part {
+ for (instruction_names) |n| if (std.mem.eql(u8, path, n)) return .instructions;
+ if (std.mem.eql(u8, path, hooks_path)) return .hooks;
+ if (under(path, skills_dir)) |rest| {
+ const slash = std.mem.indexOfScalar(u8, rest, '/') orelse {
+ const stem = stripSuffix(rest, ".md") orelse return null;
+ return if (validName(stem)) .skill else null;
+ };
+ if (!validName(rest[0..slash])) return null;
+ const tail = rest[slash + 1 ..];
+ if (std.mem.eql(u8, tail, "SKILL.md")) return .skill;
+ return if (safeRel(tail, skill_depth)) .skill_file else null;
+ }
+ if (under(path, agents_dir)) |rest| {
+ const stem = stripSuffix(rest, ".md") orelse stripSuffix(rest, ".toml") orelse return null;
+ return if (validName(stem)) .subagent else null;
+ }
+ if (under(path, scripts_dir)) |rest| return if (validFile(rest)) .script else null;
+ return null;
+}
+
+/// The skill directory name a skill or skill-file path belongs to.
+pub fn skillName(path: []const u8) ?[]const u8 {
+ const rest = under(path, skills_dir) orelse return null;
+ if (std.mem.indexOfScalar(u8, rest, '/')) |slash| return rest[0..slash];
+ return stripSuffix(rest, ".md");
+}
+
+/// Lowercase letters, digits, `_` and `-`, starting with a letter or digit.
+pub fn validName(name: []const u8) bool {
+ if (name.len == 0 or name.len > 64 or !std.ascii.isAlphanumeric(name[0])) return false;
+ for (name) |c| switch (c) {
+ 'a'...'z', '0'...'9', '_', '-' => {},
+ else => return false,
+ };
+ return true;
+}
+
+fn validFile(name: []const u8) bool {
+ if (name.len == 0 or name.len > 128 or name[0] == '.') return false;
+ for (name) |c| if (!(std.ascii.isAlphanumeric(c) or c == '_' or c == '-' or c == '.')) return false;
+ return true;
+}
+
+fn safeRel(rel: []const u8, max_dirs: usize) bool {
+ var dirs: usize = 0;
+ var it = std.mem.splitScalar(u8, rel, '/');
+ while (it.next()) |seg| {
+ if (!validFile(seg)) return false;
+ if (it.peek() != null) dirs += 1;
+ }
+ return dirs <= max_dirs;
+}
+
+fn under(path: []const u8, dir: []const u8) ?[]const u8 {
+ if (path.len <= dir.len + 1 or !std.mem.startsWith(u8, path, dir) or path[dir.len] != '/') return null;
+ return path[dir.len + 1 ..];
+}
+
+fn stripSuffix(s: []const u8, suffix: []const u8) ?[]const u8 {
+ return if (std.mem.endsWith(u8, s, suffix)) s[0 .. s.len - suffix.len] else null;
+}
+
+/// Read the harness out of the checkout rooted at `root`.
+pub fn load(io: Io, arena: Allocator, root: Io.Dir) !Loaded {
+ var files: std.ArrayList(File) = .empty;
+ var skipped: std.ArrayList([]const u8) = .empty;
+ for (instruction_names) |name| {
+ const data = root.readFileAlloc(io, name, arena, .limited(max_file_bytes + 1)) catch continue;
+ if (std.mem.trim(u8, data, " \t\r\n").len == 0) continue;
+ try addFile(arena, &files, &skipped, name, data);
+ break; // graff reads only the first non-empty one
+ }
+ try walk(io, arena, root, skills_dir, &files, &skipped, skill_depth + 1);
+ try walk(io, arena, root, agents_dir, &files, &skipped, 0);
+ try walk(io, arena, root, scripts_dir, &files, &skipped, 0);
+ if (try readHooks(io, arena, root)) |hooks| try files.append(arena, .{ .path = hooks_path, .data = hooks });
+ std.mem.sort(File, files.items, {}, lessThan);
+ return .{ .tree = .{ .files = files.items }, .skipped = skipped.items };
+}
+
+fn addFile(arena: Allocator, files: *std.ArrayList(File), skipped: *std.ArrayList([]const u8), path: []const u8, data: []const u8) !void {
+ if (data.len > max_file_bytes) return skipped.append(arena, path);
+ try files.append(arena, .{ .path = path, .data = data });
+}
+
+fn walk(io: Io, arena: Allocator, root: Io.Dir, dir_path: []const u8, files: *std.ArrayList(File), skipped: *std.ArrayList([]const u8), depth: usize) !void {
+ var dir = root.openDir(io, dir_path, .{ .iterate = true }) catch return;
+ defer dir.close(io);
+ var it = dir.iterate();
+ while (it.next(io) catch null) |entry| {
+ const path = try std.fmt.allocPrint(arena, "{s}/{s}", .{ dir_path, entry.name });
+ switch (entry.kind) {
+ .directory => if (depth > 0) try walk(io, arena, root, path, files, skipped, depth - 1),
+ .file => {
+ if (classify(path) == null) {
+ try skipped.append(arena, path);
+ continue;
+ }
+ const data = root.readFileAlloc(io, path, arena, .limited(max_file_bytes + 1)) catch |err| switch (err) {
+ error.StreamTooLong => {
+ try skipped.append(arena, path);
+ continue;
+ },
+ else => return err,
+ };
+ try addFile(arena, files, skipped, path, data);
+ },
+ else => {},
+ }
+ }
+}
+
+/// The hooks object of the settings file, re-serialized, or null when absent.
+fn readHooks(io: Io, arena: Allocator, root: Io.Dir) !?[]const u8 {
+ const data = root.readFileAlloc(io, hooks_path, arena, .limited(1 << 20)) catch return null;
+ const v = std.json.parseFromSliceLeaky(Value, arena, data, .{}) catch return null;
+ if (v != .object) return null;
+ const hooks = v.object.get("hooks") orelse return null;
+ return try std.json.Stringify.valueAlloc(arena, hooks, .{ .whitespace = .indent_2 });
+}
+
+fn lessThan(_: void, a: File, b: File) bool {
+ return std.mem.lessThan(u8, a.path, b.path);
+}
+
+/// Make the harness of the checkout at `root` exactly `tree`: surface files
+/// the tree lacks are removed, every tree file is written, and an earlier
+/// instruction file that would shadow the tree's is deleted. Off-surface files
+/// and the rest of the settings file are left alone. Meant for a probe
+/// checkout, not the user's own.
+pub fn write(io: Io, arena: Allocator, tree: Tree, root: Io.Dir) !void {
+ const current = try load(io, arena, root);
+ for (current.tree.files) |f| {
+ if (tree.get(f.path) != null) continue;
+ if (classify(f.path) == .hooks) {
+ try mergeHooks(io, arena, root, null);
+ continue;
+ }
+ try root.deleteFile(io, f.path);
+ if (skillName(f.path)) |name| {
+ const skill_dir = try std.fmt.allocPrint(arena, "{s}/{s}", .{ skills_dir, name });
+ pruneEmpty(io, arena, root, skill_dir);
+ }
+ }
+ const keep = if (tree.instructions()) |f| f.path else "";
+ for (instruction_names) |name| {
+ if (std.mem.eql(u8, name, keep)) break;
+ root.deleteFile(io, name) catch |err| switch (err) {
+ error.FileNotFound => {},
+ else => return err,
+ };
+ }
+ for (tree.files) |f| {
+ if (classify(f.path) == .hooks) {
+ try mergeHooks(io, arena, root, f.data);
+ continue;
+ }
+ if (std.fs.path.dirname(f.path)) |parent| try root.createDirPath(io, parent);
+ try root.writeFile(io, .{ .sub_path = f.path, .data = f.data });
+ }
+}
+
+/// Remove a skill directory's now-empty subdirectories and the directory
+/// itself; a non-empty one stays.
+fn pruneEmpty(io: Io, arena: Allocator, root: Io.Dir, dir_path: []const u8) void {
+ var dir = root.openDir(io, dir_path, .{ .iterate = true }) catch return;
+ var it = dir.iterate();
+ while (it.next(io) catch null) |entry| {
+ if (entry.kind != .directory) continue;
+ const sub = std.fmt.allocPrint(arena, "{s}/{s}", .{ dir_path, entry.name }) catch continue;
+ pruneEmpty(io, arena, root, sub);
+ }
+ dir.close(io);
+ root.deleteDir(io, dir_path) catch {};
+}
+
+/// Set (or, with null, remove) the "hooks" key of the settings file.
+fn mergeHooks(io: Io, arena: Allocator, root: Io.Dir, hooks: ?[]const u8) !void {
+ var settings: std.json.ObjectMap = .empty;
+ if (root.readFileAlloc(io, hooks_path, arena, .limited(1 << 20))) |data| {
+ const v = std.json.parseFromSliceLeaky(Value, arena, data, .{}) catch return error.InvalidSettings;
+ if (v != .object) return error.InvalidSettings;
+ settings = v.object;
+ } else |err| switch (err) {
+ error.FileNotFound => if (hooks == null) return,
+ else => return err,
+ }
+ if (hooks) |text| {
+ const v = try std.json.parseFromSliceLeaky(Value, arena, text, .{});
+ try settings.put(arena, "hooks", v);
+ } else if (!settings.orderedRemove("hooks")) return;
+ if (std.fs.path.dirname(hooks_path)) |parent| try root.createDirPath(io, parent);
+ const out = try std.json.Stringify.valueAlloc(arena, Value{ .object = settings }, .{ .whitespace = .indent_2 });
+ try root.writeFile(io, .{ .sub_path = hooks_path, .data = out });
+}
+
+pub const Digest = [32]u8;
+
+/// Content address of a tree: path, length and bytes of every file in order.
+pub fn digest(tree: Tree) Digest {
+ var h = std.crypto.hash.sha2.Sha256.init(.{});
+ h.update("graff.harness_tree.v1\n");
+ for (tree.files) |f| {
+ h.update(f.path);
+ h.update(&.{0});
+ var len: [8]u8 = undefined;
+ std.mem.writeInt(u64, &len, f.data.len, .little);
+ h.update(&len);
+ h.update(f.data);
+ }
+ var out: Digest = undefined;
+ h.final(&out);
+ return out;
+}
+
+/// The first 16 hex digits, the width fleet ids use.
+pub fn shortId(d: Digest) [16]u8 {
+ const hex = std.fmt.bytesToHex(d, .lower);
+ return hex[0..16].*;
+}
+
+pub const Diff = struct {
+ added: []const []const u8,
+ removed: []const []const u8,
+ modified: []const []const u8,
+
+ pub fn empty(self: Diff) bool {
+ return self.added.len == 0 and self.removed.len == 0 and self.modified.len == 0;
+ }
+};
+
+/// Paths `after` adds, drops, or changes relative to `before`.
+pub fn diff(arena: Allocator, before: Tree, after: Tree) !Diff {
+ var added: std.ArrayList([]const u8) = .empty;
+ var removed: std.ArrayList([]const u8) = .empty;
+ var modified: std.ArrayList([]const u8) = .empty;
+ for (after.files) |f| {
+ const old = before.get(f.path) orelse {
+ try added.append(arena, f.path);
+ continue;
+ };
+ if (!std.mem.eql(u8, old, f.data)) try modified.append(arena, f.path);
+ }
+ for (before.files) |f| if (after.get(f.path) == null) try removed.append(arena, f.path);
+ return .{ .added = added.items, .removed = removed.items, .modified = modified.items };
+}
diff --git a/src/harness_tree_check.zig b/src/harness_tree_check.zig
new file mode 100644
index 00000000..de3b18f6
--- /dev/null
+++ b/src/harness_tree_check.zig
@@ -0,0 +1,156 @@
+//! Is a proposed harness tree one graff can run? Every problem comes back as
+//! one line of actionable prose, because the list is fed verbatim to the
+//! proposer as retry feedback: say what is wrong and what to do instead.
+//!
+//! Beyond shape (paths, sizes, frontmatter, hook JSON), two rules keep a
+//! refine loop honest. References to helper scripts must resolve inside the
+//! tree, so a probe never fails on a file the proposal forgot. And text the
+//! proposal adds may not talk about grading: the loop improves the work from
+//! how runs behaved, and a harness that cites a rubric or a grader is tuning
+//! to a measurement it should never see.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+const tree_mod = @import("harness_tree.zig");
+const Tree = tree_mod.Tree;
+
+pub const grader_words = [_][]const u8{ "rubric", "grader", "grading criteria", "hidden test", "judge's", "the judge" };
+const hook_events = [_][]const u8{ "pre_tool", "post_tool", "turn_end" };
+
+/// Every problem with `tree`, one line each; empty means it can run. `base`
+/// is the tree the proposal started from: grading language already in it is
+/// the user's and is not held against the proposal.
+pub fn problems(arena: Allocator, tree: Tree, base: ?Tree) ![]const []const u8 {
+ var out: std.ArrayList([]const u8) = .empty;
+ if (tree.files.len > tree_mod.max_files)
+ try say(arena, &out, "the harness has {d} files; keep it to {d} or fewer by merging or dropping the least useful ones", .{ tree.files.len, tree_mod.max_files });
+ var n_instructions: usize = 0;
+ for (tree.files, 0..) |f, i| {
+ if (i > 0 and !std.mem.lessThan(u8, tree.files[i - 1].path, f.path))
+ try say(arena, &out, "{s} appears twice or out of order; list each path once", .{f.path});
+ const part = tree_mod.classify(f.path) orelse {
+ try say(arena, &out, "{s} is not part of the harness; use the instruction file, {s}/<name>/SKILL.md, {s}/<name>.md, {s}/<file>, or the hooks in {s} (names are lowercase letters, digits, `_` or `-`)", .{ f.path, tree_mod.skills_dir, tree_mod.agents_dir, tree_mod.scripts_dir, tree_mod.hooks_path });
+ continue;
+ };
+ if (f.data.len > tree_mod.max_file_bytes)
+ try say(arena, &out, "{s} is {d} bytes; keep each file under {d}", .{ f.path, f.data.len, tree_mod.max_file_bytes });
+ switch (part) {
+ .instructions => {
+ n_instructions += 1;
+ const cap = @import("context_limits.zig").agents_md_bytes;
+ if (f.data.len > cap)
+ try say(arena, &out, "{s} is {d} bytes but graff reads only the first {d}; move detail into a skill and keep the instruction file short", .{ f.path, f.data.len, cap });
+ },
+ .skill => try checkSkill(arena, &out, f),
+ .skill_file => {
+ const name = tree_mod.skillName(f.path).?;
+ const doc = try std.fmt.allocPrint(arena, "{s}/{s}/SKILL.md", .{ tree_mod.skills_dir, name });
+ if (tree.get(doc) == null)
+ try say(arena, &out, "{s} belongs to skill `{s}`, which has no {s}; add one or drop the file", .{ f.path, name, doc });
+ },
+ .subagent => {
+ const base_name = std.fs.path.basename(f.path);
+ if (@import("agent_file.zig").parse(arena, base_name, f.data) == null)
+ try say(arena, &out, "{s} has no prompt body; a subagent file needs instructions after its frontmatter", .{f.path});
+ },
+ .script => {},
+ .hooks => try checkHooks(arena, &out, f.data),
+ }
+ try checkScriptRefs(arena, &out, tree, f);
+ try checkGraderWords(arena, &out, f, if (base) |b| b.get(f.path) else null);
+ }
+ if (n_instructions > 1)
+ try say(arena, &out, "the harness has {d} instruction files but graff reads only the first non-empty one; keep a single instruction file", .{n_instructions});
+ return out.items;
+}
+
+/// The problems as one message, or null when there are none.
+pub fn report(arena: Allocator, tree: Tree, base: ?Tree) !?[]const u8 {
+ const list = try problems(arena, tree, base);
+ if (list.len == 0) return null;
+ var buf: std.Io.Writer.Allocating = .init(arena);
+ for (list) |p| try buf.writer.print("- {s}\n", .{p});
+ return buf.writer.buffered();
+}
+
+fn say(arena: Allocator, out: *std.ArrayList([]const u8), comptime fmt: []const u8, args: anytype) !void {
+ try out.append(arena, try std.fmt.allocPrint(arena, fmt, args));
+}
+
+fn checkSkill(arena: Allocator, out: *std.ArrayList([]const u8), f: tree_mod.File) !void {
+ const dir_name = tree_mod.skillName(f.path).?;
+ const doc = @import("skill_docs.zig").parseDoc(dir_name, f.data);
+ if (!std.mem.startsWith(u8, f.data, "---"))
+ return say(arena, out, "{s} needs frontmatter: start it with ---, then `name: {s}` and a one-line `description:`, then ---", .{ f.path, dir_name });
+ if (doc.desc.len == 0)
+ try say(arena, out, "{s} has no `description:`; graff shows only the description until the skill is loaded, so say when to use it", .{f.path});
+ if (!std.mem.eql(u8, doc.name, dir_name))
+ try say(arena, out, "{s} is named `{s}` in its frontmatter; use `name: {s}` to match its directory", .{ f.path, doc.name, dir_name });
+ if (doc.body.len == 0) try say(arena, out, "{s} has no body after its frontmatter", .{f.path});
+}
+
+fn checkHooks(arena: Allocator, out: *std.ArrayList([]const u8), data: []const u8) !void {
+ const v = std.json.parseFromSliceLeaky(Value, arena, data, .{}) catch
+ return say(arena, out, "the hooks are not valid JSON; write an object like {{\"pre_tool\": [{{\"match\": \"shell\", \"command\": \"python3 .harness/scripts/guard.py\"}}]}}", .{});
+ if (v != .object) return say(arena, out, "the hooks must be a JSON object keyed by pre_tool, post_tool or turn_end", .{});
+ var it = v.object.iterator();
+ while (it.next()) |kv| {
+ const event = kv.key_ptr.*;
+ if (!known(event)) {
+ try say(arena, out, "hook event `{s}` does not exist; use pre_tool, post_tool or turn_end", .{event});
+ continue;
+ }
+ if (kv.value_ptr.* != .array) {
+ try say(arena, out, "hooks.{s} must be a list of {{\"command\": ...}} objects", .{event});
+ continue;
+ }
+ for (kv.value_ptr.array.items, 0..) |h, i| {
+ const cmd = if (h == .object) h.object.get("command") else null;
+ if (cmd == null or cmd.? != .string or std.mem.trim(u8, cmd.?.string, " \t").len == 0)
+ try say(arena, out, "hooks.{s}[{d}] needs a non-empty string `command`", .{ event, i });
+ }
+ }
+}
+
+fn known(event: []const u8) bool {
+ for (hook_events) |e| if (std.mem.eql(u8, e, event)) return true;
+ return false;
+}
+
+/// Every `.harness/scripts/<file>` a harness file mentions must be in the tree.
+fn checkScriptRefs(arena: Allocator, out: *std.ArrayList([]const u8), tree: Tree, f: tree_mod.File) !void {
+ const prefix = tree_mod.scripts_dir ++ "/";
+ var at: usize = 0;
+ while (std.mem.indexOfPos(u8, f.data, at, prefix)) |start| {
+ var end = start + prefix.len;
+ while (end < f.data.len and isPathByte(f.data[end])) end += 1;
+ while (end > start + prefix.len and f.data[end - 1] == '.') end -= 1; // sentence period
+ at = end;
+ if (end == start + prefix.len) continue;
+ const ref = f.data[start..end];
+ if (tree.get(ref) == null)
+ try say(arena, out, "{s} mentions {s}, which is not in the harness; add the script or drop the mention", .{ f.path, ref });
+ }
+}
+
+fn isPathByte(c: u8) bool {
+ return std.ascii.isAlphanumeric(c) or c == '_' or c == '-' or c == '.' or c == '/';
+}
+
+fn checkGraderWords(arena: Allocator, out: *std.ArrayList([]const u8), f: tree_mod.File, before: ?[]const u8) !void {
+ for (grader_words) |word| {
+ if (countFold(f.data, word) > if (before) |b| countFold(b, word) else 0)
+ try say(arena, out, "{s} adds text about `{s}`; describe the work itself, not how it is graded", .{ f.path, word });
+ }
+}
+
+fn countFold(hay: []const u8, needle: []const u8) usize {
+ if (needle.len == 0 or hay.len < needle.len) return 0;
+ var n: usize = 0;
+ var i: usize = 0;
+ while (i + needle.len <= hay.len) : (i += 1) {
+ if (std.ascii.eqlIgnoreCase(hay[i .. i + needle.len], needle)) n += 1;
+ }
+ return n;
+}
diff --git a/src/harness_tree_cli.zig b/src/harness_tree_cli.zig
new file mode 100644
index 00000000..c2711eec
--- /dev/null
+++ b/src/harness_tree_cli.zig
@@ -0,0 +1,152 @@
+//! `graff harness-tree …`: the harness tree from the command line.
+//!
+//! show [dir] [--json] the files that make up the harness, with its id
+//! digest [dir] just the id
+//! check <dir> [--base <d>] can graff run the harness in <dir>? (exit 1 if not)
+//! apply <from> <to> make <to>'s harness exactly <from>'s
+//! diff <a> <b> paths added, removed and changed from a to b
+//!
+//! `check` is for a harness-only directory (one `apply` exported): every file
+//! in it must be part of the harness, so a misplaced file is reported rather
+//! than silently left out.
+
+const std = @import("std");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const tree_mod = @import("harness_tree.zig");
+const check_mod = @import("harness_tree_check.zig");
+
+const usage =
+ \\usage: graff harness-tree show [dir] [--json]
+ \\ graff harness-tree digest [dir]
+ \\ graff harness-tree check <dir> [--base <dir>]
+ \\ graff harness-tree apply <from> <to>
+ \\ graff harness-tree diff <a> <b>
+ \\
+;
+
+pub fn command(io: Io, arena: Allocator, args: []const []const u8) !void {
+ var buf: [4096]u8 = undefined;
+ var w = Io.File.stdout().writer(io, &buf);
+ const out = &w.interface;
+ defer out.flush() catch {};
+ const code = run(io, arena, out, args) catch |err| {
+ try out.print("graff harness-tree: {s}\n", .{@errorName(err)});
+ try out.flush();
+ std.process.exit(1);
+ };
+ if (code != 0) {
+ try out.flush();
+ std.process.exit(code);
+ }
+}
+
+pub fn run(io: Io, arena: Allocator, out: *Io.Writer, args: []const []const u8) !u8 {
+ const action = if (args.len > 0) args[0] else "show";
+ var pos: std.ArrayList([]const u8) = .empty;
+ var json = false;
+ var base_dir: ?[]const u8 = null;
+ var i: usize = 1;
+ while (i < args.len) : (i += 1) {
+ if (std.mem.eql(u8, args[i], "--json")) {
+ json = true;
+ } else if (std.mem.eql(u8, args[i], "--base") and i + 1 < args.len) {
+ i += 1;
+ base_dir = args[i];
+ } else try pos.append(arena, args[i]);
+ }
+ const p = pos.items;
+ if (std.mem.eql(u8, action, "show")) return show(io, arena, out, if (p.len > 0) p[0] else ".", json);
+ if (std.mem.eql(u8, action, "digest")) {
+ const loaded = try loadAt(io, arena, if (p.len > 0) p[0] else ".");
+ try out.print("{s}\n", .{&std.fmt.bytesToHex(tree_mod.digest(loaded.tree), .lower)});
+ return 0;
+ }
+ if (std.mem.eql(u8, action, "check") and p.len == 1) return check(io, arena, out, p[0], base_dir);
+ if (std.mem.eql(u8, action, "apply") and p.len == 2) {
+ const from = try loadAt(io, arena, p[0]);
+ try Io.Dir.cwd().createDirPath(io, p[1]);
+ var dest = try Io.Dir.cwd().openDir(io, p[1], .{});
+ defer dest.close(io);
+ try tree_mod.write(io, arena, from.tree, dest);
+ try out.print("{s}\n", .{&tree_mod.shortId(tree_mod.digest(from.tree))});
+ return 0;
+ }
+ if (std.mem.eql(u8, action, "diff") and p.len == 2) {
+ const a = try loadAt(io, arena, p[0]);
+ const b = try loadAt(io, arena, p[1]);
+ const d = try tree_mod.diff(arena, a.tree, b.tree);
+ for (d.added) |path| try out.print("+ {s}\n", .{path});
+ for (d.removed) |path| try out.print("- {s}\n", .{path});
+ for (d.modified) |path| try out.print("~ {s}\n", .{path});
+ return 0;
+ }
+ try out.writeAll(usage);
+ return 2;
+}
+
+fn loadAt(io: Io, arena: Allocator, path: []const u8) !tree_mod.Loaded {
+ var dir = try Io.Dir.cwd().openDir(io, path, .{});
+ defer dir.close(io);
+ return tree_mod.load(io, arena, dir);
+}
+
+fn show(io: Io, arena: Allocator, out: *Io.Writer, path: []const u8, json: bool) !u8 {
+ const loaded = try loadAt(io, arena, path);
+ const id = tree_mod.digest(loaded.tree);
+ if (json) {
+ var s: std.json.Stringify = .{ .writer = out };
+ try s.beginObject();
+ try s.objectField("digest");
+ try s.write(&std.fmt.bytesToHex(id, .lower));
+ try s.objectField("files");
+ try s.beginArray();
+ for (loaded.tree.files) |f| {
+ try s.write(.{ .path = f.path, .part = tree_mod.classify(f.path).?.label(), .bytes = f.data.len });
+ }
+ try s.endArray();
+ try s.objectField("skipped");
+ try s.write(loaded.skipped);
+ try s.endObject();
+ try out.writeAll("\n");
+ return 0;
+ }
+ try out.print("harness {s} ({d} files)\n", .{ &tree_mod.shortId(id), loaded.tree.files.len });
+ for (loaded.tree.files) |f| try out.print(" {s:<12} {d:>7} {s}\n", .{ tree_mod.classify(f.path).?.label(), f.data.len, f.path });
+ for (loaded.skipped) |s| try out.print(" {s:<12} {s:>7} {s}\n", .{ "skipped", "-", s });
+ return 0;
+}
+
+fn check(io: Io, arena: Allocator, out: *Io.Writer, path: []const u8, base_dir: ?[]const u8) !u8 {
+ var dir = try Io.Dir.cwd().openDir(io, path, .{ .iterate = true });
+ defer dir.close(io);
+ const loaded = try tree_mod.load(io, arena, dir);
+ const base: ?tree_mod.Tree = if (base_dir) |b| (try loadAt(io, arena, b)).tree else null;
+ var lines: std.ArrayList([]const u8) = .empty;
+ try strays(io, arena, dir, "", &lines, 6);
+ for (loaded.skipped) |s| {
+ if (tree_mod.classify(s) != null) try lines.append(arena, try std.fmt.allocPrint(arena, "{s} is over {d} bytes; keep each file smaller", .{ s, tree_mod.max_file_bytes }));
+ }
+ try lines.appendSlice(arena, try check_mod.problems(arena, loaded.tree, base));
+ if (lines.items.len == 0) {
+ try out.print("ok {s}\n", .{&tree_mod.shortId(tree_mod.digest(loaded.tree))});
+ return 0;
+ }
+ for (lines.items) |l| try out.print("- {s}\n", .{l});
+ return 1;
+}
+
+/// Every file under a harness-only directory that is not part of the harness.
+fn strays(io: Io, arena: Allocator, root: Io.Dir, rel: []const u8, lines: *std.ArrayList([]const u8), depth: usize) !void {
+ var dir = (if (rel.len == 0) root.openDir(io, ".", .{ .iterate = true }) else root.openDir(io, rel, .{ .iterate = true })) catch return;
+ defer dir.close(io);
+ var it = dir.iterate();
+ while (it.next(io) catch null) |entry| {
+ const path = if (rel.len == 0) try arena.dupe(u8, entry.name) else try std.fmt.allocPrint(arena, "{s}/{s}", .{ rel, entry.name });
+ switch (entry.kind) {
+ .directory => if (depth > 0) try strays(io, arena, root, path, lines, depth - 1),
+ .file => if (tree_mod.classify(path) == null) try lines.append(arena, try std.fmt.allocPrint(arena, "{s} is not part of the harness; move it to {s}/<name>/, {s}/ or {s}/, or drop it", .{ path, tree_mod.skills_dir, tree_mod.agents_dir, tree_mod.scripts_dir })),
+ else => {},
+ }
+ }
+}
diff --git a/src/harness_tree_tests.zig b/src/harness_tree_tests.zig
new file mode 100644
index 00000000..55540844
--- /dev/null
+++ b/src/harness_tree_tests.zig
@@ -0,0 +1,219 @@
+//! The harness tree: what is on the surface, load/write round trips, the
+//! digest, and the checker's feedback.
+
+const std = @import("std");
+const tree_mod = @import("harness_tree.zig");
+const check_mod = @import("harness_tree_check.zig");
+const cli = @import("harness_tree_cli.zig");
+const Tree = tree_mod.Tree;
+const File = tree_mod.File;
+
+const skill_doc = "---\nname: totals\ndescription: Use when a report sums columns.\n---\nRun python3 .harness/scripts/sum.py before answering.\n";
+const agent_doc = "---\nname: reviewer\ndescription: Reviews a draft.\n---\nRead the draft and list concrete defects.\n";
+
+fn put(dir: std.Io.Dir, path: []const u8, data: []const u8) !void {
+ const io = std.testing.io;
+ if (std.fs.path.dirname(path)) |parent| try dir.createDirPath(io, parent);
+ try dir.writeFile(io, .{ .sub_path = path, .data = data });
+}
+
+fn sample(dir: std.Io.Dir) !void {
+ try put(dir, "AGENTS.md", "Be terse.\n");
+ try put(dir, "CLAUDE.md", "shadowed by AGENTS.md\n");
+ try put(dir, ".agents/skills/totals/SKILL.md", skill_doc);
+ try put(dir, ".agents/skills/totals/scripts/check.py", "print('ok')\n");
+ try put(dir, ".agents/skills/Bad Name/SKILL.md", skill_doc);
+ try put(dir, ".harness/agents/reviewer.md", agent_doc);
+ try put(dir, ".harness/scripts/sum.py", "print(1)\n");
+ try put(dir, ".harness/settings.json", "{\"model\":\"keep-me\",\"hooks\":{\"turn_end\":[{\"command\":\"true\"}]}}");
+ try put(dir, "src/main.py", "not harness\n");
+}
+
+test "the harness surface is the files graff loads to decide how it works" {
+ const cases = .{
+ .{ "AGENTS.md", tree_mod.Part.instructions },
+ .{ "CLAUDE.md", tree_mod.Part.instructions },
+ .{ ".agents/skills/totals/SKILL.md", tree_mod.Part.skill },
+ .{ ".agents/skills/totals.md", tree_mod.Part.skill },
+ .{ ".agents/skills/totals/scripts/check.py", tree_mod.Part.skill_file },
+ .{ ".harness/agents/reviewer.md", tree_mod.Part.subagent },
+ .{ ".harness/agents/reviewer.toml", tree_mod.Part.subagent },
+ .{ ".harness/scripts/sum.py", tree_mod.Part.script },
+ .{ ".harness/settings.json", tree_mod.Part.hooks },
+ };
+ inline for (cases) |c| try std.testing.expectEqual(@as(?tree_mod.Part, c[1]), tree_mod.classify(c[0]));
+ for ([_][]const u8{
+ "README.md", "src/main.zig", ".agents/skills/Bad Name/SKILL.md",
+ ".agents/skills/x/../../etc", ".agents/skills/x/a/b/c/d.py", ".harness/agents/notes.txt",
+ ".harness/scripts/sub/x.py", ".harness/scripts/.hidden", ".agents/skills",
+ "docs/AGENTS.md",
+ }) |path| try std.testing.expectEqual(@as(?tree_mod.Part, null), tree_mod.classify(path));
+}
+
+test "load reads the active instruction file, skills, subagents, scripts and hooks" {
+ const io = std.testing.io;
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var tmp = std.testing.tmpDir(.{ .iterate = true });
+ defer tmp.cleanup();
+ try sample(tmp.dir);
+
+ const loaded = try tree_mod.load(io, a, tmp.dir);
+ const paths = [_][]const u8{
+ ".agents/skills/totals/SKILL.md", ".agents/skills/totals/scripts/check.py", ".harness/agents/reviewer.md",
+ ".harness/scripts/sum.py", ".harness/settings.json", "AGENTS.md",
+ };
+ try std.testing.expectEqual(paths.len, loaded.tree.files.len);
+ for (paths, loaded.tree.files) |want, got| try std.testing.expectEqualStrings(want, got.path);
+ try std.testing.expectEqual(@as(usize, 1), loaded.skipped.len);
+ try std.testing.expectEqualStrings(".agents/skills/Bad Name/SKILL.md", loaded.skipped[0]);
+ // The hooks file carries only the hooks object, not the other settings.
+ const hooks = loaded.tree.get(".harness/settings.json").?;
+ try std.testing.expect(std.mem.indexOf(u8, hooks, "turn_end") != null);
+ try std.testing.expect(std.mem.indexOf(u8, hooks, "keep-me") == null);
+ try std.testing.expectEqual(@as(usize, 0), (try check_mod.problems(a, loaded.tree, null)).len);
+}
+
+test "write makes a checkout's harness exactly the tree and leaves the rest alone" {
+ const io = std.testing.io;
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var src = std.testing.tmpDir(.{ .iterate = true });
+ defer src.cleanup();
+ var dst = std.testing.tmpDir(.{ .iterate = true });
+ defer dst.cleanup();
+ try sample(src.dir);
+ const tree = (try tree_mod.load(io, a, src.dir)).tree;
+
+ // The destination has a stale skill, other settings, and project files.
+ try put(dst.dir, ".agents/skills/stale/SKILL.md", skill_doc);
+ try put(dst.dir, ".agents/skills/stale/scripts/old.py", "x\n");
+ try put(dst.dir, ".harness/settings.json", "{\"theme\":\"dark\"}");
+ try put(dst.dir, "src/app.py", "project code\n");
+ try tree_mod.write(io, a, tree, dst.dir);
+
+ const again = (try tree_mod.load(io, a, dst.dir)).tree;
+ try std.testing.expectEqualSlices(u8, &tree_mod.digest(tree), &tree_mod.digest(again));
+ try std.testing.expectError(error.FileNotFound, dst.dir.access(io, ".agents/skills/stale", .{}));
+ const settings = try dst.dir.readFileAlloc(io, ".harness/settings.json", a, .limited(1 << 16));
+ try std.testing.expect(std.mem.indexOf(u8, settings, "\"theme\"") != null);
+ try std.testing.expect(std.mem.indexOf(u8, settings, "turn_end") != null);
+ try dst.dir.access(io, "src/app.py", .{});
+
+ // Dropping the hooks removes only that key.
+ var no_hooks: std.ArrayList(File) = .empty;
+ for (tree.files) |f| if (tree_mod.classify(f.path) != .hooks) try no_hooks.append(a, f);
+ try tree_mod.write(io, a, .{ .files = no_hooks.items }, dst.dir);
+ const after = try dst.dir.readFileAlloc(io, ".harness/settings.json", a, .limited(1 << 16));
+ try std.testing.expect(std.mem.indexOf(u8, after, "\"theme\"") != null);
+ try std.testing.expect(std.mem.indexOf(u8, after, "hooks") == null);
+}
+
+test "a tree whose instruction file is CLAUDE.md removes an AGENTS.md that would shadow it" {
+ const io = std.testing.io;
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var dst = std.testing.tmpDir(.{ .iterate = true });
+ defer dst.cleanup();
+ try put(dst.dir, "AGENTS.md", "old rules\n");
+ const files = [_]File{.{ .path = "CLAUDE.md", .data = "new rules\n" }};
+ try tree_mod.write(io, a, .{ .files = &files }, dst.dir);
+ try std.testing.expectError(error.FileNotFound, dst.dir.access(io, "AGENTS.md", .{}));
+ const loaded = try tree_mod.load(io, a, dst.dir);
+ try std.testing.expectEqualStrings("CLAUDE.md", loaded.tree.instructions().?.path);
+}
+
+test "the digest names the content and diff names the changed paths" {
+ const a_files = [_]File{ .{ .path = "AGENTS.md", .data = "one" }, .{ .path = ".harness/scripts/x.py", .data = "x" } };
+ const b_files = [_]File{ .{ .path = "AGENTS.md", .data = "two" }, .{ .path = ".harness/agents/r.md", .data = "r" } };
+ const t1: Tree = .{ .files = &a_files };
+ const t2: Tree = .{ .files = &b_files };
+ try std.testing.expectEqualSlices(u8, &tree_mod.digest(t1), &tree_mod.digest(.{ .files = &a_files }));
+ try std.testing.expect(!std.mem.eql(u8, &tree_mod.digest(t1), &tree_mod.digest(t2)));
+ // Moving bytes between path and data must not collide.
+ const c1 = [_]File{.{ .path = "AGENTS.md", .data = "ab" }};
+ const c2 = [_]File{.{ .path = "AGENTS.mda", .data = "b" }};
+ try std.testing.expect(!std.mem.eql(u8, &tree_mod.digest(.{ .files = &c1 }), &tree_mod.digest(.{ .files = &c2 })));
+
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const d = try tree_mod.diff(arena_state.allocator(), t1, t2);
+ try std.testing.expectEqualStrings(".harness/agents/r.md", d.added[0]);
+ try std.testing.expectEqualStrings(".harness/scripts/x.py", d.removed[0]);
+ try std.testing.expectEqualStrings("AGENTS.md", d.modified[0]);
+ try std.testing.expect((try tree_mod.diff(arena_state.allocator(), t1, t1)).empty());
+}
+
+fn expectProblem(list: []const []const u8, needle: []const u8) !void {
+ for (list) |p| if (std.mem.indexOf(u8, p, needle) != null) return;
+ std.debug.print("no problem mentions {s}; got:\n", .{needle});
+ for (list) |p| std.debug.print(" {s}\n", .{p});
+ return error.TestExpectedProblem;
+}
+
+test "check says what is wrong with a proposal and how to fix it" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const long = try a.alloc(u8, @import("context_limits.zig").agents_md_bytes + 1);
+ @memset(long, 'x');
+ const files = [_]File{
+ .{ .path = ".agents/skills/loose/scripts/a.py", .data = "x" },
+ .{ .path = ".agents/skills/nofront/SKILL.md", .data = "just a body\n" },
+ .{ .path = ".agents/skills/totals/SKILL.md", .data = "---\nname: total\ndescription: d\n---\nUse .harness/scripts/missing.py.\n" },
+ .{ .path = ".harness/agents/empty.md", .data = "---\nname: empty\n---\n" },
+ .{ .path = ".harness/settings.json", .data = "{\"on_start\":[],\"pre_tool\":[{\"match\":\"shell\"}]}" },
+ .{ .path = "AGENTS.md", .data = long },
+ .{ .path = "notes/idea.md", .data = "x" },
+ };
+ const list = try check_mod.problems(a, .{ .files = &files }, null);
+ try expectProblem(list, "skill `loose`, which has no");
+ try expectProblem(list, "nofront/SKILL.md needs frontmatter");
+ try expectProblem(list, "use `name: totals`");
+ try expectProblem(list, "missing.py, which is not in the harness");
+ try expectProblem(list, "empty.md has no prompt body");
+ try expectProblem(list, "hook event `on_start` does not exist");
+ try expectProblem(list, "hooks.pre_tool[0] needs a non-empty string `command`");
+ try expectProblem(list, "graff reads only the first");
+ try expectProblem(list, "notes/idea.md is not part of the harness");
+}
+
+test "check rejects grading language a proposal adds but not what the base already had" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const base = [_]File{.{ .path = "AGENTS.md", .data = "Our rubric for reviews lives in docs/.\n" }};
+ const same = [_]File{.{ .path = "AGENTS.md", .data = "Our rubric for reviews lives in docs/.\nBe terse.\n" }};
+ const gamed = [_]File{.{ .path = "AGENTS.md", .data = "Our rubric for reviews lives in docs/.\nThe grader wants a table; match the Rubric.\n" }};
+ try std.testing.expectEqual(@as(usize, 0), (try check_mod.problems(a, .{ .files = &same }, .{ .files = &base })).len);
+ const list = try check_mod.problems(a, .{ .files = &gamed }, .{ .files = &base });
+ try expectProblem(list, "`rubric`");
+ try expectProblem(list, "`grader`");
+}
+
+test "harness-tree apply exports a harness that check accepts and digests the same" {
+ const io = std.testing.io;
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var tmp = std.testing.tmpDir(.{ .iterate = true });
+ defer tmp.cleanup();
+ try sample(tmp.dir);
+ const root = try std.fmt.allocPrint(a, ".zig-cache/tmp/{s}", .{tmp.sub_path});
+ const exported = try std.fmt.allocPrint(a, "{s}/exported", .{root});
+
+ var sink: std.Io.Writer.Allocating = .init(a);
+ try std.testing.expectEqual(@as(u8, 0), try cli.run(io, a, &sink.writer, &.{ "apply", root, exported }));
+ sink.clearRetainingCapacity();
+ try std.testing.expectEqual(@as(u8, 0), try cli.run(io, a, &sink.writer, &.{ "check", exported, "--base", root }));
+ try std.testing.expect(std.mem.startsWith(u8, sink.writer.buffered(), "ok "));
+
+ // A file the proposer put outside the surface is reported, not ignored.
+ try put(tmp.dir, "exported/skills/new/SKILL.md", skill_doc);
+ sink.clearRetainingCapacity();
+ try std.testing.expectEqual(@as(u8, 1), try cli.run(io, a, &sink.writer, &.{ "check", exported }));
+ try std.testing.expect(std.mem.indexOf(u8, sink.writer.buffered(), "skills/new/SKILL.md is not part of the harness") != null);
+}
diff --git a/src/skill_docs.zig b/src/skill_docs.zig
index 48e60734..e96a0f4a 100644
--- a/src/skill_docs.zig
+++ b/src/skill_docs.zig
@@ -76,14 +76,14 @@ pub const tool_schema =
\\{"type": "object", "properties": {"name": {"type": "string", "description": "Skill name to load; omit to list every available skill"}}}
;
-const Parsed = struct { name: []const u8, desc: []const u8, body: []const u8 };
+pub const Parsed = struct { name: []const u8, desc: []const u8, body: []const u8 };
/// Split a SKILL.md into frontmatter fields + body. Same YAML-ish shape as
/// fleet.zig's persona files: a leading "---\n…\n---\n" block with `name:` and
/// `description:` lines. No frontmatter is fine — the file is all body and the
/// name comes from the filename. Comptime-callable (the bundled skills are
/// parsed at build time).
-fn parseDoc(fallback_name: []const u8, data: []const u8) Parsed {
+pub fn parseDoc(fallback_name: []const u8, data: []const u8) Parsed {
var out: Parsed = .{ .name = fallback_name, .desc = "", .body = std.mem.trim(u8, data, " \t\r\n") };
// A CRLF checkout (Windows CI, notepad-authored skills) opens "---\r\n";
// the rest of the parser already tolerates \r via per-line trims.
diff --git a/src/startup.zig b/src/startup.zig
index a6a61168..08146acc 100644
--- a/src/startup.zig
+++ b/src/startup.zig
@@ -420,6 +420,13 @@ pub fn runSubcommand(io: Io, gpa: Allocator, arena: Allocator, init: std.process
return true;
}
+ // `graff harness-tree …`: the harness (instructions, skills, subagents,
+ // scripts, hooks) as one value: show, digest, check, apply, diff.
+ if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "harness-tree")) {
+ try @import("harness_tree_cli.zig").command(io, arena, flags.positionals.items[1..]);
+ return true;
+ }
+
// `graff servers [stop <pid>|prune]`: background servers graff started —
// this session's or an earlier one's (#199).
if (flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "servers")) {
diff --git a/src/test_hooks.zig b/src/test_hooks.zig
index 1611424b..19dfbeb1 100644
--- a/src/test_hooks.zig
+++ b/src/test_hooks.zig
@@ -341,6 +341,7 @@ test {
_ = @import("image_sniff.zig"); // #1762: image media type from the bytes
_ = @import("catalog_bounded.zig"); // model discovery: catalog GETs never hold boot past a budget
_ = @import("opaque_state_persist_tests.zig"); // #1686: a resumed session keeps its compaction-state count
+ _ = @import("harness_tree_tests.zig"); // the harness as one value: surface, load/write, digest, check
_ = @import("oauth_callback.zig");
_ = @import("cache_key_tests.zig"); // ADR 0223: moved off http_headers.zig (600-line cap)
_ = @import("router_headers_tests.zig"); // moved off http_headers.zig (600-line cap)