From aef42e8ee81109299909eb72c2a78d1faefd5a49 Mon Sep 17 00:00:00 2001 From: theMackabu Date: Thu, 9 Apr 2026 11:42:09 -0700 Subject: [PATCH] add harness for agent structures prevent agents from straying from the point when using agents --- .github/agents/check_repo_knowledge.js | 137 ++++++++++++++++++ .github/agents/check_repo_structure.js | 116 ++++++++++++++++ .github/agents/route_validation.js | 184 +++++++++++++++++++++++++ .github/agents/util_repo_root.js | 5 + .github/workflows/repo-knowledge.yml | 31 +++++ .gitignore | 7 +- AGENTS.md | 74 ++++++++++ ARCHITECTURE.md | 83 +++++++++++ CONTRIBUTING.md | 13 ++ docs/exec-plans/active/README.md | 17 +++ docs/exec-plans/completed/README.md | 9 ++ docs/exec-plans/index.md | 31 +++++ docs/exec-plans/tech-debt.md | 17 +++ docs/repo/index.md | 36 +++++ docs/repo/testing.md | 45 ++++++ maidfile.toml | 9 ++ 16 files changed, 809 insertions(+), 5 deletions(-) create mode 100644 .github/agents/check_repo_knowledge.js create mode 100644 .github/agents/check_repo_structure.js create mode 100644 .github/agents/route_validation.js create mode 100644 .github/agents/util_repo_root.js create mode 100644 .github/workflows/repo-knowledge.yml create mode 100644 AGENTS.md create mode 100644 ARCHITECTURE.md create mode 100644 docs/exec-plans/active/README.md create mode 100644 docs/exec-plans/completed/README.md create mode 100644 docs/exec-plans/index.md create mode 100644 docs/exec-plans/tech-debt.md create mode 100644 docs/repo/index.md create mode 100644 docs/repo/testing.md diff --git a/.github/agents/check_repo_knowledge.js b/.github/agents/check_repo_knowledge.js new file mode 100644 index 0000000..3ce1d62 --- /dev/null +++ b/.github/agents/check_repo_knowledge.js @@ -0,0 +1,137 @@ +#!/usr/bin/env node + +import fs from 'node:fs'; +import path from 'node:path'; +import { repoRoot } from './util_repo_root.js'; + +const docs = new Map([ + [ + 'AGENTS.md', + { + requiredLinks: new Set(['ARCHITECTURE.md', 'docs/repo/index.md', 'docs/repo/testing.md', 'docs/exec-plans/index.md']), + maxLines: 90 + } + ], + [ + 'ARCHITECTURE.md', + { + requiredLinks: new Set(['docs/repo/testing.md', 'docs/exec-plans/index.md', 'meson.build']) + } + ], + [ + 'docs/repo/index.md', + { + requiredLinks: new Set(['AGENTS.md', 'ARCHITECTURE.md', 'BUILDING.md', 'CONTRIBUTING.md', 'docs/repo/testing.md', 'docs/exec-plans/index.md']) + } + ], + [ + 'docs/repo/testing.md', + { + requiredLinks: new Set(['docs/exec-plans/index.md']) + } + ], + [ + 'docs/exec-plans/index.md', + { + requiredLinks: new Set(['docs/exec-plans/active/README.md', 'docs/exec-plans/completed/README.md', 'docs/exec-plans/tech-debt.md']) + } + ], + [ + 'docs/exec-plans/active/README.md', + { + requiredLinks: new Set() + } + ], + [ + 'docs/exec-plans/completed/README.md', + { + requiredLinks: new Set() + } + ], + [ + 'docs/exec-plans/tech-debt.md', + { + requiredLinks: new Set() + } + ] +]); + +const markdownLinkPattern = /\[[^\]]+\]\(([^)]+)\)/g; +const requiredMetadata = ['Status:', 'Last reviewed:', 'Owner:']; + +function toRepoRelative(targetPath) { + return path.relative(repoRoot, targetPath).split(path.sep).join('/'); +} + +function resolveLink(docPath, rawLink) { + if (!rawLink || rawLink.startsWith('#')) { + return null; + } + + const [target] = rawLink.split('#', 1); + if (target.includes('://') || target.startsWith('mailto:') || target.startsWith('data:')) { + return null; + } + + return path.resolve(path.dirname(docPath), target); +} + +function checkDoc(docRelPath, config) { + const errors = []; + const docPath = path.join(repoRoot, docRelPath); + if (!fs.existsSync(docPath)) return [`missing required doc: ${docRelPath}`]; + + const content = fs.readFileSync(docPath, 'utf8'); + const lines = content.split(/\r?\n/); + const head = lines.slice(0, 8).join('\n'); + + for (const key of requiredMetadata) { + if (!head.includes(key)) errors.push(`${docRelPath}: missing metadata field '${key}'`); + } + + if (config.maxLines !== undefined && lines.length > config.maxLines) { + errors.push(`${docRelPath}: exceeds ${config.maxLines} lines; keep the entrypoint concise`); + } + + const discoveredLinks = new Set(); + for (const match of content.matchAll(markdownLinkPattern)) { + const rawLink = match[1].trim(); + const resolved = resolveLink(docPath, rawLink); + if (resolved === null) continue; + + if (!fs.existsSync(resolved)) { + errors.push(`${docRelPath}: broken link '${rawLink}'`); + continue; + } + + discoveredLinks.add(toRepoRelative(resolved)); + } + + const missingLinks = [...config.requiredLinks].sort().filter(link => !discoveredLinks.has(link)); + for (const missing of missingLinks) { + errors.push(`${docRelPath}: missing required cross-link to '${missing}'`); + } + + return errors; +} + +function main() { + const allErrors = []; + + for (const [docRelPath, config] of docs.entries()) { + allErrors.push(...checkDoc(docRelPath, config)); + } + + if (allErrors.length > 0) { + console.error('repo knowledge check failed:'); + for (const error of allErrors) { + console.error(` - ${error}`); + } + process.exitCode = 1; + return; + } + + console.log('repo knowledge check passed'); +} + +main(); diff --git a/.github/agents/check_repo_structure.js b/.github/agents/check_repo_structure.js new file mode 100644 index 0000000..cc01421 --- /dev/null +++ b/.github/agents/check_repo_structure.js @@ -0,0 +1,116 @@ +#!/usr/bin/env node + +import fs from 'node:fs'; +import path from 'node:path'; +import childProcess from 'node:child_process'; +import { repoRoot } from './util_repo_root.js'; + +function parseArgs(argv) { + const result = { + files: [], + filesFrom: null + }; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + if (arg === '--files-from') { + result.filesFrom = argv[index + 1] || null; + index += 1; + continue; + } + + result.files.push(arg); + } + + return result; +} + +function readChangedFilesFromGit() { + const commands = [ + ['git', ['diff', '--name-only', '--cached']], + ['git', ['diff', '--name-only']], + ['git', ['ls-files', '--others', '--exclude-standard']] + ]; + + const files = new Set(); + for (const [command, args] of commands) { + const output = childProcess.execFileSync(command, args, { + cwd: repoRoot, + encoding: 'utf8' + }); + + for (const line of output.split(/\r?\n/)) { + const trimmed = line.trim(); + if (!trimmed) { + continue; + } + files.add(trimmed); + } + } + + return [...files].sort(); +} + +function loadFiles(options) { + if (options.filesFrom) { + const contents = fs.readFileSync(path.resolve(repoRoot, options.filesFrom), 'utf8'); + return contents + .split(/\r?\n/) + .map(line => line.trim()) + .filter(Boolean); + } + + if (options.files.length > 0) { + return options.files; + } + + return readChangedFilesFromGit(); +} + +function normalize(filePath) { + return filePath.split(path.sep).join('/'); +} + +function main() { + const options = parseArgs(process.argv.slice(2)); + const changedFiles = loadFiles(options).map(normalize); + const errors = []; + const notes = []; + + for (const filePath of changedFiles) { + if (filePath.startsWith('build/')) { + errors.push(`${filePath}: do not commit build output; keep build artifacts local`); + } + + if (filePath.startsWith('docs/output/') || filePath.startsWith('docs/symbols/')) { + errors.push(`${filePath}: generated docs artifacts do not belong in normal source changes`); + } + + if (/^todo\/.+\.md$/u.test(filePath)) { + errors.push(`${filePath}: durable markdown should live under docs/repo/ or docs/exec-plans/, not todo/`); + } + + if (filePath.startsWith('vendor/')) { + notes.push(`${filePath}: vendored dependency change detected; keep it isolated and document the reason in an execution plan`); + } + } + + if (errors.length > 0) { + console.error('repo structure check failed:'); + for (const error of errors) { + console.error(` - ${error}`); + } + process.exitCode = 1; + return; + } + + console.log(changedFiles.length === 0 ? 'repo structure check passed (no changed files)' : 'repo structure check passed'); + + if (notes.length > 0) { + console.log(''); + console.log('notes:'); + for (const note of notes) console.log(` - ${note}`); + } +} + +main(); diff --git a/.github/agents/route_validation.js b/.github/agents/route_validation.js new file mode 100644 index 0000000..1370bda --- /dev/null +++ b/.github/agents/route_validation.js @@ -0,0 +1,184 @@ +#!/usr/bin/env node + +import fs from 'node:fs'; +import path from 'node:path'; +import { repoRoot } from './util_repo_root.js'; +import childProcess from 'node:child_process'; + +function parseArgs(argv) { + const result = { + files: [], + filesFrom: null + }; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + if (arg === '--files-from') { + result.filesFrom = argv[index + 1] || null; + index += 1; + continue; + } + + result.files.push(arg); + } + + return result; +} + +function readChangedFilesFromGit() { + const commands = [ + ['git', ['diff', '--name-only', '--cached']], + ['git', ['diff', '--name-only']], + ['git', ['ls-files', '--others', '--exclude-standard']] + ]; + + const files = new Set(); + for (const [command, args] of commands) { + const output = childProcess.execFileSync(command, args, { + cwd: repoRoot, + encoding: 'utf8' + }); + + for (const line of output.split(/\r?\n/)) { + const trimmed = line.trim(); + if (!trimmed) { + continue; + } + files.add(trimmed); + } + } + + return [...files].sort(); +} + +function loadFiles(options) { + if (options.filesFrom) { + const contents = fs.readFileSync(path.resolve(repoRoot, options.filesFrom), 'utf8'); + return contents + .split(/\r?\n/) + .map(line => line.trim()) + .filter(Boolean); + } + + if (options.files.length > 0) { + return options.files; + } + + return readChangedFilesFromGit(); +} + +function normalize(filePath) { + return filePath.split(path.sep).join('/'); +} + +function addRecommendation(recommendations, command, reason) { + if (!recommendations.has(command)) recommendations.set(command, reason); +} + +function isDocsOnly(files) { + return files.every( + filePath => + filePath === 'AGENTS.md' || + filePath === 'ARCHITECTURE.md' || + filePath === 'CONTRIBUTING.md' || + filePath === 'BUILDING.md' || + filePath.startsWith('docs/') || + filePath.endsWith('.md') + ); +} + +function main() { + const options = parseArgs(process.argv.slice(2)); + const changedFiles = loadFiles(options).map(normalize); + const recommendations = new Map(); + const notes = []; + + if (changedFiles.length === 0) { + console.log('No changed files detected.'); + console.log(''); + console.log('Recommended validation:'); + console.log('- maid knowledge'); + return; + } + + if (isDocsOnly(changedFiles)) { + addRecommendation(recommendations, 'maid knowledge', 'docs-only change set'); + } + + for (const filePath of changedFiles) { + if (filePath === 'AGENTS.md' || filePath === 'ARCHITECTURE.md' || filePath.startsWith('docs/repo/') || filePath.startsWith('docs/exec-plans/')) { + addRecommendation(recommendations, 'maid knowledge', 'repo knowledge docs changed'); + } + + if ( + filePath.startsWith('src/silver/') || + filePath.startsWith('src/gc/') || + filePath === 'src/runtime.c' || + filePath === 'src/ant.c' || + filePath === 'src/main.c' || + filePath === 'src/errors.c' || + filePath === 'src/descriptors.c' || + filePath === 'src/shapes.c' + ) { + addRecommendation(recommendations, 'meson compile -C build', 'runtime or engine core changed'); + addRecommendation(recommendations, './build/ant examples/spec/run.js', 'engine-level behavior can affect broad language semantics'); + } + + if ( + filePath.startsWith('src/modules/') || + filePath.startsWith('src/esm/') || + filePath.startsWith('src/builtins/') || + filePath.startsWith('src/http/') || + filePath.startsWith('src/net/') || + filePath.startsWith('src/streams/') + ) { + addRecommendation(recommendations, 'meson compile -C build', 'runtime-facing modules or I/O code changed'); + addRecommendation(recommendations, './build/ant examples/spec/run.js', 'shared runtime semantics may have shifted'); + + const stem = path.basename(filePath, path.extname(filePath)); + if (stem) { + notes.push(`Consider running focused tests that match '${stem}', for example: rg --files tests | rg '${stem}'`); + } + } + + if ( + filePath === 'meson.build' || + filePath.startsWith('meson/') || + filePath === 'maidfile.toml' || + filePath.startsWith('.github/workflows/') || + filePath.startsWith('.github/actions/') || + filePath.startsWith('libant/') + ) { + addRecommendation(recommendations, 'meson setup build --reconfigure', 'build graph or automation changed'); + addRecommendation(recommendations, 'meson compile -C build', 'build configuration changes should still produce a binary'); + } + + if (filePath.startsWith('.github/agents/')) { + addRecommendation(recommendations, 'maid knowledge', 'tooling change touched the repo harness'); + } + + if (filePath.startsWith('tests/')) { + addRecommendation(recommendations, 'meson compile -C build', 'tests should run against a fresh binary'); + addRecommendation(recommendations, `./build/ant ${filePath}`, 'a focused regression test changed'); + } + } + + console.log('Changed files:'); + for (const filePath of changedFiles) { + console.log(`- ${filePath}`); + } + + console.log(''); + console.log('Recommended validation:'); + for (const [command, reason] of recommendations.entries()) { + console.log(`- ${command} # ${reason}`); + } + + if (notes.length > 0) { + console.log(''); + console.log('Notes:'); + for (const note of [...new Set(notes)]) console.log(`- ${note}`); + } +} + +main(); diff --git a/.github/agents/util_repo_root.js b/.github/agents/util_repo_root.js new file mode 100644 index 0000000..2a734e2 --- /dev/null +++ b/.github/agents/util_repo_root.js @@ -0,0 +1,5 @@ +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const dirname = path.dirname(fileURLToPath(import.meta.url)); +export const repoRoot = path.resolve(dirname, '..', '..'); diff --git a/.github/workflows/repo-knowledge.yml b/.github/workflows/repo-knowledge.yml new file mode 100644 index 0000000..a78374d --- /dev/null +++ b/.github/workflows/repo-knowledge.yml @@ -0,0 +1,31 @@ +name: Repo Knowledge + +on: + push: + pull_request: + workflow_dispatch: + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + fetch-depth: 0 + - name: Validate repo knowledge docs + run: node .github/agents/check_repo_knowledge.js + - name: Collect changed files + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + git fetch origin "${{ github.base_ref }}" --depth=1 + git diff --name-only "origin/${{ github.base_ref }}...HEAD" > .changed-files + elif [ -n "${{ github.event.before }}" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then + git diff --name-only "${{ github.event.before }}" "${{ github.sha }}" > .changed-files + else + git ls-files > .changed-files + fi + - name: Validate changed-file structure + run: node .github/agents/check_repo_structure.js --files-from .changed-files + - name: Suggest validation commands + run: node .github/agents/route_validation.js --files-from .changed-files diff --git a/.gitignore b/.gitignore index 1a8c5b9..d4efdd4 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,6 @@ /build /traces -/docs /todo/* /src/pkg/.zig-cache @@ -24,6 +23,7 @@ /wpt /tools +/zoo.sh /vendor/*/ /vendor/.wraplock @@ -32,10 +32,7 @@ *.todo *.trace -zoo.sh -AGENTS.md - node_modules bun.lock pnpm-lock.yaml -package-lock.json \ No newline at end of file +package-lock.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..762055d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# AGENTS.md + +Status: active +Last reviewed: 2026-04-09 +Owner: Ant maintainers + +This file is the table of contents for agent work in Ant. Start here, then +open the smallest linked document that matches the task instead of loading the +entire repository into context. + +## Start Here + +- Repository map: [ARCHITECTURE.md](ARCHITECTURE.md) +- Knowledge index: [docs/repo/index.md](docs/repo/index.md) +- Build setup: [BUILDING.md](BUILDING.md) +- Contribution rules: [CONTRIBUTING.md](CONTRIBUTING.md) +- Durable execution plans: [docs/exec-plans/index.md](docs/exec-plans/index.md) + +## Fast Path + +- Build from an existing configured tree: `meson compile -C build` +- Fresh local setup: `maid setup` +- Run a focused test file: `./build/ant tests/test_.cjs` +- Run the spec suite: `./build/ant examples/spec/run.js` +- Validate repo knowledge docs: `maid knowledge` +- Validate changed-file boundaries: `maid structure` +- Route the current diff to the right checks: `maid validate_changes` + +## Codebase Map + +- `src/main.c`, `src/ant.c`, and `src/runtime.c` wire process startup and the + runtime entrypoints. +- `src/silver/` contains the parser, compiler, VM, and JIT-facing execution + logic for the Ant Silver engine. +- `src/gc/` contains heap layout, roots, strings, ropes, and collection logic. +- `src/modules/` and `src/builtins/` implement built-in modules and host APIs. +- `src/http/`, `src/net/`, and `src/streams/` are the transport and I/O stack. +- `src/pkg/` is the Zig package manager; `src/strip/` is the Rust type-stripper. +- `meson/` and `meson.build` define the build graph and generated headers. +- `.github/agents/` contains the lightweight repo-harness checks and validation + router used by local tasks and CI. +- `tests/`, `examples/spec/`, and `tools/wpt/` cover targeted + runtime tests, the spec suite, and conformance harnesses. + +See [ARCHITECTURE.md](ARCHITECTURE.md) for subsystem boundaries and change +guidance. + +## Change Rules + +- Prefer changes in `src/`, `include/`, `meson/`, `tests/`, `tools/`, and `.github/agents/`. +- Treat `vendor/`, `build/ as generated or third-party surfaces. + Only edit them when the task explicitly requires it. +- Keep durable design notes and execution history in versioned markdown under + `docs/`. Treat `todo/` as scratch space, not the source of truth. +- Add or update tests when behavior changes. +- When touching build or runtime invariants, document the reasoning in + [docs/exec-plans/index.md](docs/exec-plans/index.md) or a linked plan if the + work spans multiple steps. + +## Which Doc To Open Next + +- Build, toolchain, or platform issue: + [BUILDING.md](BUILDING.md) +- Runtime or subsystem question: + [ARCHITECTURE.md](ARCHITECTURE.md) +- Test selection or validation scope: + [docs/repo/testing.md](docs/repo/testing.md) +- Long-running or multi-step task: + [docs/exec-plans/index.md](docs/exec-plans/index.md) + +## Keep This File Small + +`AGENTS.md` should stay a concise entrypoint. Add durable detail to the linked +documents instead of expanding this file into a manual. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..6be4dc7 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,83 @@ +# Architecture + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +This document is the top-level map for Ant's runtime and build graph. It is +meant to answer "where should this change live?" before anyone starts editing. + +## Design Priorities + +- Keep the runtime small and fast to start. +- Prefer explicit, in-repo implementations over opaque build-time magic. +- Isolate third-party code under `vendor/` and keep Ant-owned logic in `src/`, + `include/`, `meson/`, `tools/`, and `tests/`. + +## Runtime Layers + +### Process and startup + +- `src/main.c` is the CLI executable entrypoint. +- `src/ant.c` and `src/runtime.c` handle runtime initialization and shared + process setup. +- `src/cli/` contains command-line specific behavior such as version and package + commands. + +### JavaScript engine + +- `src/silver/` contains the language pipeline: lexer, parser, compiler, + directives, VM glue, and bytecode operations. +- `src/gc/` contains memory management primitives and object/string handling. +- Files like `src/errors.c`, `src/descriptors.c`, and `src/shapes.c` support + core engine behavior shared across subsystems. + +### Host platform surface + +- `src/modules/` implements built-in modules and runtime-facing JS APIs. +- `src/builtins/` holds bundled JavaScript shims and Node-compatible modules. +- `src/http/`, `src/net/`, and `src/streams/` provide protocol, networking, and + streaming support. +- `src/esm/` handles module loading, export wiring, and built-in bundle access. + +### Tooling and generated inputs + +- `src/tools/` generates bundled sources such as the builtin bundle and JS + snapshot. +- `src/core/` stores TypeScript sources and runtime metadata that feed + generation steps. +- `src/pkg/` is the Zig package manager. +- `src/strip/` is the Rust type-stripper used during builds. +- `meson/` and the root [meson.build](meson.build) describe the build graph, + dependency setup, and custom code generation targets. + +## Tests and Validation + +- `tests/` contains focused runtime tests. +- `examples/spec/` is the main spec regression suite. +- `test262/`, and `tools/wpt/` support broader conformance and standards work. +- See [docs/repo/testing.md](docs/repo/testing.md) for the recommended command + set by change type. + +## Change Placement Guidelines + +- Parser, bytecode, execution semantics, or JIT-adjacent work belongs under + `src/silver/`. +- Heap, string, or lifetime bugs usually belong under `src/gc/`. +- Built-in API behavior should land in `src/modules/`, `src/builtins/`, or + `src/esm/` depending on whether the change is C runtime code, bundled JS, or + module-loader plumbing. +- Networking and protocol work should stay in `src/http/`, `src/net/`, or + `src/streams/` unless it is only wiring. +- Build graph changes should prefer `meson/` or `meson.build`; avoid burying + build logic in ad-hoc shell scripts. + +## Boundaries To Preserve + +- Do not hand-edit third-party code in `vendor/` unless the task is explicitly a + vendored dependency change. +- Do not check durable architecture knowledge into `todo/`; use + [docs/exec-plans/index.md](docs/exec-plans/index.md) for multi-step work and + `docs/repo/` for stable reference docs. +- Keep generated outputs reproducible. If a generated file changes, update or + document the generator path in the same change. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e14baf..2790911 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,19 @@ meson compile -C build For detailed build instructions including debug builds, ASan builds,
ccache setup, and Windows/Linux/macOS specifics, see [BUILDING.md](BUILDING.md). +## Repository Knowledge + +Ant keeps agent-facing repository context in versioned markdown so future +changes do not depend on chat history or tribal knowledge. + +- Start with [AGENTS.md](AGENTS.md) for the quick repository map +- Use [ARCHITECTURE.md](ARCHITECTURE.md) for subsystem boundaries +- Use [docs/repo/index.md](docs/repo/index.md) for durable workflow docs +- Use [docs/exec-plans/index.md](docs/exec-plans/index.md) for multi-step work +- Run `maid knowledge` after updating these docs +- Run `maid structure` to catch generated-path and scratch-doc violations +- Run `maid validate_changes` to see the recommended validation set for the current diff + ## How to Contribute ### Reporting Bugs diff --git a/docs/exec-plans/active/README.md b/docs/exec-plans/active/README.md new file mode 100644 index 0000000..3884fac --- /dev/null +++ b/docs/exec-plans/active/README.md @@ -0,0 +1,17 @@ +# Active Plans + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +Store in-progress execution plans here. + +Recommended sections: + +- Goal +- Scope +- Constraints +- Task list +- Decision log +- Validation status +- Follow-ups diff --git a/docs/exec-plans/completed/README.md b/docs/exec-plans/completed/README.md new file mode 100644 index 0000000..7da4dfc --- /dev/null +++ b/docs/exec-plans/completed/README.md @@ -0,0 +1,9 @@ +# Completed Plans + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +Move finished execution plans here once the associated work has landed. Keep +the final validation notes and follow-up references intact so future changes +can reuse the decision history. diff --git a/docs/exec-plans/index.md b/docs/exec-plans/index.md new file mode 100644 index 0000000..6420ce9 --- /dev/null +++ b/docs/exec-plans/index.md @@ -0,0 +1,31 @@ +# Execution Plans + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +Use this directory for durable, versioned plans when work spans multiple +decisions, checkpoints, or follow-up changes. + +## Layout + +- Active plans: [active/README.md](active/README.md) +- Completed plans: [completed/README.md](completed/README.md) +- Technical debt tracker: [tech-debt.md](tech-debt.md) + +## When To Create A Plan + +- The task spans multiple subsystems. +- The work will happen across multiple commits or pull requests. +- Validation has meaningful risk, tradeoffs, or deferred follow-ups. +- Future contributors will need the reasoning, not just the final diff. + +## Plan Expectations + +- State the problem, constraints, and intended outcome up front. +- Keep a short decision log as the work evolves. +- Record validation status and unresolved risks. +- Move finished plans into `completed/` once the work is done. + +`todo/` can still hold scratch notes, but durable execution history belongs in +this directory. diff --git a/docs/exec-plans/tech-debt.md b/docs/exec-plans/tech-debt.md new file mode 100644 index 0000000..aa763d2 --- /dev/null +++ b/docs/exec-plans/tech-debt.md @@ -0,0 +1,17 @@ +# Technical Debt Tracker + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +Use this file to record debt that is important enough to preserve but not yet +scheduled. + +## Format + +- Area: +- Issue: +- Impact: +- Proposed fix: +- Owner: +- Status: diff --git a/docs/repo/index.md b/docs/repo/index.md new file mode 100644 index 0000000..5e0e3d3 --- /dev/null +++ b/docs/repo/index.md @@ -0,0 +1,36 @@ +# Repo Knowledge Index + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +This directory is the durable, versioned knowledge base for Ant's repository +workflow. Start with the smallest document that answers the task at hand. + +## Core References + +- Agent entrypoint: [../../AGENTS.md](../../AGENTS.md) +- Architecture map: [../../ARCHITECTURE.md](../../ARCHITECTURE.md) +- Build instructions: [../../BUILDING.md](../../BUILDING.md) +- Contribution guide: [../../CONTRIBUTING.md](../../CONTRIBUTING.md) +- Test selection guide: [testing.md](testing.md) +- Execution plans and tech debt: [../exec-plans/index.md](../exec-plans/index.md) + +## How To Use This Knowledge Base + +- Keep stable reference material here instead of burying it in chat history or + scratch notes. +- Use execution plans for work that spans multiple commits, decisions, or + checkpoints. +- Keep `AGENTS.md` short and link into this directory rather than expanding it. +- Run `maid knowledge` after updating these docs so stale links or missing + metadata fail fast. +- Run `maid structure` to guard changed-file boundaries. +- Run `maid validate_changes` to route the current diff to the smallest safe + validation set. + +## When To Add A New Doc + +- Add a new document when a rule, subsystem map, or workflow is reused across + tasks and would otherwise be repeated in prompts or review comments. +- Prefer one focused file per topic over a single large manual. diff --git a/docs/repo/testing.md b/docs/repo/testing.md new file mode 100644 index 0000000..97567a2 --- /dev/null +++ b/docs/repo/testing.md @@ -0,0 +1,45 @@ +# Testing Guide + +Status: active +Last reviewed: 2026-04-09 +Owner: theMackabu + +This guide keeps validation proportional to the change while still protecting runtime behavior. + +## Common Commands + +- Build the configured tree: `maid build` +- Fresh setup and build: `maid setup && maid build` +- Run one runtime test: `./build/ant tests/test_.cjs` +- Run the spec suite: `./build/ant examples/spec/run.js --all` +- Validate repo knowledge docs: `maid knowledge` +- Validate changed-file boundaries: `maid structure` +- Ask the harness what to run for the current diff: `maid validate_changes` + +## Validation By Change Type + +### Runtime behavior in `src/modules/`, `src/esm/`, or `src/builtins/` + +- Run the most specific `tests/test_.cjs` coverage you can find or add. +- Run `./build/ant examples/spec/run.js ` when the change affects shared runtime + semantics or built-ins used broadly across the platform. + +### Engine behavior in `src/silver/`, `src/gc/`, or runtime core files + +- Rebuild with `maid build`. +- Run focused regression tests first. +- Run `./build/ant examples/spec/run.js --all` before landing behavior changes. + +### Build or toolchain changes + +- Re-run the affected Meson flow (`maid setup`, `maid reconfigure`, or + `maid build`). +- Validate any new repo-knowledge or workflow checks locally with + `maid knowledge` and `maid structure`. + +## Notes + +- Keep new tests close to the behavior they protect so future agent runs can + discover the expected pattern quickly. +- If the right validation is expensive or unavailable, document the gap in the + associated [execution plan](../exec-plans/index.md). diff --git a/maidfile.toml b/maidfile.toml index 26d015e..47d127c 100644 --- a/maidfile.toml +++ b/maidfile.toml @@ -23,6 +23,15 @@ script = [".github/download.sh", "open .github/artifacts"] [tasks.run] script = ["maid build -q", "./build/ant %{arg.1}"] +[tasks.knowledge] +script = "ant .github/agents/check_repo_knowledge.js" + +[tasks.structure] +script = "ant .github/agents/check_repo_structure.js" + +[tasks.validate_changes] +script = "ant .github/agents/route_validation.js" + [tasks.amber] script = "amber build .github/install/install.ab install.sh" -- 2.51.2