AGENTS.md

1# NSForge Agent Harness
2 
3Workspace instructions for autonomous agents (Copilot, Cline, Codex, OpenHands,
4Hermes, …) working in the **Neurosymbolic Forge (NSForge)** repository.
5 
6## Goal
7 
8Help build and operate NSForge — an MCP server that turns *concepts* into
9verifiable, traceable *entities* (symbols → derivations → algorithms). The AI
10orchestrates; deterministic tools reify. See
11`docs/reification-ladder-direction.md` for the north star.
12 
13## North Star
14 
15> Every symbol / equation / value / line of code in a final result must have a
16> tool call as its "birth certificate" (provenance). The AI must not hand-derive
17> any of them.
18 
19Success = the amount the AI computes by hand approaches zero.
20 
21## Working Style
22 
23- Use Traditional Chinese unless the user asks otherwise.
24- Prefer exact file paths, command output summaries, and verification results.
25- Offload mechanical/deterministic steps (symbolic calculation, simplification,
26  code generation) to tools — do not hand-derive formulas.
27- When changing behavior, add a focused regression test under `tests/`.
28 
29## Ground Truth: one command
30 
31Before and after changes, verify against the green baseline:
32 
33```bash
34python scripts/check.py            # all gates
35python scripts/check.py --json     # machine-readable summary (for agents)
36python scripts/check.py --gates lint,type,test   # subset
37```
38 
39Gates: lint, format, type, import, manifest, test, bench, generic, provenance, harness, diff. Exit code 0 = green.
40(bench = derivation-correctness of `benchmarks/*.json` through the L3 orchestrator;
41generic = arbitrary unseen compositions derive correctly, proving NSForge is a
42derivation *calculus*, not a hand-built formula library; provenance = every
43benchmark derivation carries a complete tool-provenance ledger, no hand-derived leaks;
44harness = the harness self-checks its own invariants — version single-source,
45self-describing tools, and gate/doc parity — so agents can trust the signal.)
46 
47## Repo Layout (DDD)
48 
49- `src/nsforge/domain/`: pure domain models/value objects (no I/O)
50- `src/nsforge/application/`: use-cases / orchestration
51- `src/nsforge/infrastructure/`: adapters (sympy engine, formula sources, file I/O)
52- `src/nsforge_mcp/`: MCP tool layer + server wiring (`server.py`, `tools/`)
53- `docs/agent/capabilities.json`: machine-readable tool manifest (self-describing)
54 
55## Guardrails
56 
57- Keep `src/nsforge/domain` free of I/O and infrastructure imports.
58- Do not weaken `mypy` strict or skip gates just to make checks pass.
59- Prefer `uv run ...` so tools use the project venv.
60- Avoid destructive git ops (`reset --hard`, `clean -fdx`) unless asked.
61- Never commit secrets or generated outputs (`dist/`, `.venv/`, `data/`).
62- After adding/removing an `@mcp.tool`, regenerate the manifest:
63  `python scripts/gen_capabilities.py`.
64 
65## Related Files
66 
67- `docs/reification-ladder-direction.md` — architecture direction
68- `scripts/check.py` — verification harness (ground truth)
69- `scripts/gen_capabilities.py` — capability manifest generator
70- `.github/copilot-instructions.md` — Copilot rules
71- `memory-bank/activeContext.md` — current focus
72