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