Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
3.7 KiB
Marqdo CLI — Agent / Contributor Operating Rules
Start here: read docs/DEVELOPMENT_BLUEPRINT.md before proposing code. It is the project architecture baseline. Then read docs/STATUS.md (what is actually implemented), the relevant spec/ files, docs/adr/ for frozen decisions, docs/contributor-guide.md for the workflow, and tests/README.md plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative.
Non-negotiable architectural constraints
- New independent language/toolchain. Do not silently modify
cflmy/marqdoor claim compatibility with its syntax, package format or plugin ABI. - CommonMark/GFM/Math AST is the sole Markdown syntax structure. Do not implement a second Markdown parser or use regex heuristics to decide whether text is executable.
- Executable roles are based on AST type and valid structural context:
Strongexecution,Emphreturn, ordered list branch, bullet list loop, blockquote invocation, heading scoping. Invalid executable shapes are compile errors, not ordinary prose fallbacks. - Prose and executable nodes may mix freely in one function/branch/loop body. Prose itself never causes an action.
- Marqdo is executed by its own Rust interpreter. Python/Node are optional foreign kernels, never the official compiler target.
- Code fences and math expressions create inert native
CodeandFormulavalues. Evaluation requires explicit calls and relevant capability grants. - YAML project/dependency and frontmatter imports must be explicit. Markdown Links are static references, not implicit calls or imports.
- Third-party plugins require a versioned C ABI and SDK. A C ABI is not a sandbox. Default third-party execution must be isolated; in-process native loading requires explicit trust.
- Side effects go through
CapabilityHost; do not invent host bypasses for tests, plugins, math or foreign kernels.checkandinspectcannot execute untrusted project code. - Language semantics, package format, ABI, authorization defaults or public CLI behavior changes require an ADR + tests + spec updates.
Development workflow
- Identify the affected rule and cite the section of
docs/DEVELOPMENT_BLUEPRINT.md. - Add a small
.mq.mdpositive/negative conformance fixture and define the expected Markdown AST and execution IR. - Implement only the smallest module that satisfies this fixture. Keep Markdown parser, semantic mapper, runtime and host separated.
- Run formatting, clippy, unit tests, gold tests and relevant security/ABI compatibility tests (
cargo fmt --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace,cargo test -p marqdo-cli). - Write the tradeoff and state of completion in the PR. Never say a feature is finished because a design example looks executable. Update
spec/anddocs/STATUS.mdwhen behavior or status changes; the docs describe what the code does and flag blueprint divergences explicitly.
Unresolved design topics
The blueprint's section 17 lists issues that need separate Accepted ADRs (e.g. emphasis conflicts, parameter inference ambiguity, plugin memory ownership, strict platform isolation). Use its proposed baseline for prototypes, but do not freeze these topics through undocumented code.
Priorities
P0 AST/grammar contracts → P1 independent interpreter → P2 references/CLI → P3 package/env → P4 sandbox → P5 math/foreign → P6 plugin ABI/SDK → P7 performance/release. Design the Host security boundary and ABI early, even if full implementation arrives later.
Never translate Marqdo into Python as the official execution method; never silently downgrade an invalid execution node to prose or a requested strict sandbox to an unrestricted process.