Skip to content

Commit 01e0d12

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Implement scope arrest anchor schema (#13)
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 40b620d commit 01e0d12

22 files changed

Lines changed: 962 additions & 2 deletions

‎.machine_read/ANCHOR.scope-arrest.2026-01-01.scm‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
;; ANCHOR.scope-arrest.2026-01-01.Jewell.scm (anvomidav)
2+
;; SPDX-License-Identifier: MIT OR AGPL-3.0-or-later
3+
;; SPDX-FileCopyrightText: 2026 hyperpolymath
4+
;;
5+
;; This anchor file defines the scope arrest for phase f0.
6+
;; It freezes the project identity and establishes the conformance baseline.
7+
8+
(define anchor
9+
'((schema . "hyperpolymath.anchor/1")
10+
(repo . "hyperpolymath/anvomidav")
11+
(date . "2026-01-01")
12+
(authority . "repo-superintendent")
13+
(purpose . ("Scope arrest + make repo unambiguously runnable + freeze identity."))
14+
(identity
15+
. ((project . "Anvomidav")
16+
(kind . "domain-language + CLI toolchain")
17+
(domain . "figure-skating choreography")
18+
(one-sentence . "A DSL and toolchain for expressing skating choreography and validating rule constraints.")))
19+
20+
(semantic-anchor
21+
. ((policy . "dual")
22+
(reference-impl . ("Rust workspace" "CLI is authoritative behavior"))
23+
(formal-spec . ("SPEC.core.scm defines syntax/semantics; conformance corpus is binding"))))
24+
25+
(allowed-implementation-languages
26+
. ("Rust")) ;; keep narrow in f0; editors/tooling optional later
27+
(forbidden
28+
. ("Expanding into unrelated domains"
29+
"Adding new backends"
30+
"Rewriting as a different project"))
31+
32+
(golden-path
33+
. ((smoke-test-command . "cargo test && cargo run -p anv-cli -- check examples/*")
34+
(success-criteria . ("parse+check succeeds on at least 1 example"
35+
"at least 5 invalid examples produce stable diagnostics"))))
36+
37+
(mandatory-files
38+
. ("./.machine_read/LLM_SUPERINTENDENT.scm"
39+
"./.machine_read/SPEC.core.scm"
40+
"./.machine_read/ROADMAP.f0.scm"
41+
"./conformance/"))
42+
43+
(first-pass-directives
44+
. ("Ensure README(s) do not contradict this identity."
45+
"If multiple READMEs exist, create one canonical machine README pointer (no prose needed)."
46+
"Quarantine tree-sitter/editor integration as optional: it must not block core build."
47+
"Add conformance corpus representing core grammar + rule checks."))
48+
49+
(rsr
50+
. ((target-tier . "bronze-now") (upgrade-path . "silver-after-f1")))))

‎.machine_read/AUTHORITY_STACK.scm‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
;; AUTHORITY_STACK.mustfile-nickel.scm
2+
;; SPDX-License-Identifier: MIT OR AGPL-3.0-or-later
3+
;; SPDX-FileCopyrightText: 2026 hyperpolymath
4+
;;
5+
;; Shared drop for hyperpolymath repos: defines task routing + config authority.
6+
7+
(define authority-stack
8+
'((schema . "hyperpolymath.authority-stack/1")
9+
(intent
10+
. ("Stop agentic drift and toolchain creep."
11+
"Make the repo executable via a single blessed interface."
12+
"Prevent the LLM from inventing commands, tools, or files."))
13+
14+
(operational-authority
15+
. ((local-tasks . "just")
16+
(deployment-transitions . "must")
17+
(config-manifests . "nickel")
18+
(container-engine . "podman-first")))
19+
20+
(hard-rules
21+
. ("Makefiles are forbidden."
22+
"All operations must be invoked via `just <recipe>` (local) or `must <transition>` (deployment)."
23+
"If a recipe/transition does not exist, the correct action is to ADD it (and document it), not to run ad-hoc commands."
24+
"Nickel manifests are the single source of truth for config; do not hand-edit generated outputs."
25+
"No network-required runtime paths for demos/tests unless explicitly permitted in ANCHOR."))
26+
27+
(workflow
28+
. ((first-run
29+
. ("Read ANCHOR*.scm"
30+
"Read STATE.scm"
31+
"Run: just --list"
32+
"Run: just test"
33+
"Run: just demo (if defined)"))
34+
(adding-new-capability
35+
. ("Update SPEC/ROADMAP first"
36+
"Add a `just` recipe (and tests) that implements the capability"
37+
"Only then edit code"))))
38+
39+
(tooling-contract
40+
. ((mustfile-notes
41+
. ("Mustfile is the deployment contract (physical state transitions)."
42+
"must is the supervisor/enforcer for must-spec; it routes through just where appropriate."))
43+
(nickel-notes
44+
. ("Nickel provides validated, type-safe manifests."
45+
"Prefer .ncl for machine-truth; render docs from it via your conversion pipeline."))
46+
(shell-entrypoints
47+
. ("Shell wrappers may exist; all must route to just/must without inventing extra logic."))))))

‎.machine_read/CANONICAL_README.scm‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
;; SPDX-License-Identifier: MIT OR AGPL-3.0-or-later
2+
;; SPDX-FileCopyrightText: 2025-2026 hyperpolymath
3+
;;
4+
;; CANONICAL_README.scm - Pointer to Canonical Documentation
5+
;;
6+
;; This file establishes the documentation hierarchy for the repository.
7+
;; Multiple READMEs exist for different purposes; this file clarifies authority.
8+
9+
(define canonical-docs
10+
'((schema . "hyperpolymath.canonical-docs/1")
11+
(updated . "2026-01-01")
12+
13+
;; ==========================================================================
14+
;; PRIMARY DOCUMENTATION
15+
;; ==========================================================================
16+
(primary
17+
. ((readme
18+
. ((path . "./README.adoc")
19+
(purpose . "Main project documentation, quick start, syntax examples")
20+
(authority . "canonical")))
21+
(roadmap
22+
. ((path . "./ROADMAP.adoc")
23+
(purpose . "Development phases and milestones")
24+
(authority . "canonical")))
25+
(contributing
26+
. ((path . "./CONTRIBUTING.adoc")
27+
(purpose . "How to contribute")
28+
(authority . "canonical")))
29+
(security
30+
. ((path . "./SECURITY.md")
31+
(purpose . "Security policy and vulnerability reporting")
32+
(authority . "canonical")))))
33+
34+
;; ==========================================================================
35+
;; MACHINE-READABLE DOCUMENTATION
36+
;; ==========================================================================
37+
(machine-readable
38+
. ((superintendent
39+
. ((path . "./.machine_read/LLM_SUPERINTENDENT.scm")
40+
(purpose . "Instructions for AI/LLM agents")))
41+
(spec
42+
. ((path . "./.machine_read/SPEC.core.scm")
43+
(purpose . "Core language specification (binding)")))
44+
(roadmap-f0
45+
. ((path . "./.machine_read/ROADMAP.f0.scm")
46+
(purpose . "Phase f0 scope arrest roadmap")))
47+
(state
48+
. ((path . "./STATE.scm")
49+
(purpose . "Current project state")))))
50+
51+
;; ==========================================================================
52+
;; SUPPLEMENTARY DOCUMENTATION (Non-authoritative for Core)
53+
;; ==========================================================================
54+
(supplementary
55+
. ((academic
56+
. ((path . "./docs/academic/README.adoc")
57+
(purpose . "Academic papers and formal proofs")
58+
(status . "optional")))
59+
(implementation
60+
. ((path . "./docs/IMPLEMENTATION.adoc")
61+
(purpose . "Implementation details")
62+
(status . "optional")))))
63+
64+
;; ==========================================================================
65+
;; EDITOR/TOOLING DOCUMENTATION (OPTIONAL - Does not affect core)
66+
;; ==========================================================================
67+
(optional-tooling
68+
. ((neovim
69+
. ((path . "./editors/neovim/README.md")
70+
(purpose . "Neovim integration")
71+
(status . "optional - does not block core build")))
72+
(helix
73+
. ((path . "./editors/helix/README.md")
74+
(purpose . "Helix editor integration")
75+
(status . "optional - does not block core build")))
76+
(tree-sitter
77+
. ((path . "./tree-sitter-anvomidav/")
78+
(purpose . "Tree-sitter grammar for syntax highlighting")
79+
(status . "optional - does not block core build")))))
80+
81+
;; ==========================================================================
82+
;; READING ORDER FOR NEW CONTRIBUTORS
83+
;; ==========================================================================
84+
(reading-order
85+
. (("README.adoc" . "Start here for project overview")
86+
("ROADMAP.adoc" . "Understand development phases")
87+
("CONTRIBUTING.adoc" . "How to participate")
88+
(".machine_read/SPEC.core.scm" . "Language specification")
89+
("crates/anv-cli/src/main.rs" . "CLI entry point")))))

‎.machine_read/LLM_SUPERINTENDENT.scm‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
;; SPDX-License-Identifier: MIT OR AGPL-3.0-or-later
2+
;; SPDX-FileCopyrightText: 2025-2026 hyperpolymath
3+
;;
4+
;; LLM_SUPERINTENDENT.scm - Instructions for AI/LLM agents operating on this repository
5+
;;
6+
;; This file provides machine-readable directives for LLM code assistants.
7+
8+
(define superintendent
9+
'((schema . "hyperpolymath.superintendent/1")
10+
(updated . "2026-01-01")
11+
12+
;; Project identity - DO NOT DEVIATE
13+
(identity
14+
. ((name . "Anvomidav")
15+
(kind . "domain-specific language + CLI toolchain")
16+
(domain . "figure skating choreography")
17+
(one-sentence . "A DSL and toolchain for expressing skating choreography and validating ISU rule constraints.")))
18+
19+
;; Implementation constraints
20+
(implementation
21+
. ((language . "Rust")
22+
(workspace . "Cargo.toml defines workspace members")
23+
(cli-binary . "anv-cli")
24+
(reference-behavior . "CLI output is authoritative")))
25+
26+
;; What to protect
27+
(invariants
28+
. (("Core semantics must match SPEC.core.scm")
29+
("ISU rule validation must pass for valid examples in conformance/valid/")
30+
("Invalid examples in conformance/invalid/ must produce stable diagnostics")
31+
("All 90+ tests must pass after any change")))
32+
33+
;; What is allowed
34+
(allowed
35+
. (("Bug fixes in existing crates")
36+
("Extending ISU rule coverage")
37+
("Adding new conformance tests")
38+
("Improving error messages")
39+
("Documentation improvements")))
40+
41+
;; What is forbidden
42+
(forbidden
43+
. (("Changing project identity or domain")
44+
("Adding non-Rust implementation languages")
45+
("Adding external service dependencies")
46+
("Rewriting the parser without migration plan")
47+
("Breaking existing conformance tests")))
48+
49+
;; Before making changes, verify
50+
(verification
51+
. ((smoke-test . "just smoke-test")
52+
(conformance . "just conformance")
53+
(tests . "just test")))
54+
55+
;; Operational authority - HOW to run commands
56+
(authority-stack
57+
. ((local-tasks . "just <recipe>")
58+
(see-also . ".machine_read/AUTHORITY_STACK.scm")
59+
(hard-rules
60+
. ("Makefiles are forbidden"
61+
"All operations via `just <recipe>` - do not run ad-hoc commands"
62+
"If a recipe does not exist, ADD it to justfile first"))))
63+
64+
;; Key files to understand the system
65+
(key-files
66+
. (("justfile" . "Task runner - use `just --list` to see recipes")
67+
("README.adoc" . "Project overview and quick start")
68+
("ROADMAP.adoc" . "Development phases and milestones")
69+
("Cargo.toml" . "Workspace configuration")
70+
("crates/anv-syntax/src/lib.rs" . "Lexer and parser entry")
71+
("crates/anv-semantics/src/lib.rs" . "ISU rules validation")
72+
("crates/anv-cli/src/main.rs" . "CLI entry point")
73+
(".machine_read/SPEC.core.scm" . "Core language specification")
74+
(".machine_read/AUTHORITY_STACK.scm" . "Task routing rules")))
75+
76+
;; Current phase and scope limits
77+
(phase
78+
. ((current . "f0")
79+
(focus . "Make repo unambiguously runnable and establish conformance baseline")
80+
(scope-arrest . #t)
81+
(no-new-features . #t)))))

‎.machine_read/ROADMAP.f0.scm‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
;; SPDX-License-Identifier: MIT OR AGPL-3.0-or-later
2+
;; SPDX-FileCopyrightText: 2025-2026 hyperpolymath
3+
;;
4+
;; ROADMAP.f0.scm - Phase f0: Scope Arrest & Baseline Establishment
5+
;;
6+
;; This roadmap defines the immediate stabilization phase.
7+
;; Focus: Make the repository unambiguously runnable and freeze identity.
8+
9+
(define roadmap-f0
10+
'((schema . "hyperpolymath.roadmap/1")
11+
(phase . "f0")
12+
(name . "Scope Arrest")
13+
(goal . "Establish stable, runnable baseline with conformance corpus")
14+
(started . "2026-01-01")
15+
(target-tier . "bronze")
16+
17+
;; ==========================================================================
18+
;; PHASE F0 OBJECTIVES
19+
;; ==========================================================================
20+
(objectives
21+
. (("O1" . "Repository is unambiguously runnable")
22+
("O2" . "Identity is frozen and documented")
23+
("O3" . "Conformance corpus exists with valid/invalid examples")
24+
("O4" . "Tree-sitter/editor integration is marked optional")
25+
("O5" . "Smoke test passes reliably")))
26+
27+
;; ==========================================================================
28+
;; ACCEPTANCE CRITERIA
29+
;; ==========================================================================
30+
(acceptance-criteria
31+
. ((smoke-test
32+
. ((command . "cargo test && cargo run -p anv-cli -- check examples/*")
33+
(expected . "All tests pass, at least 1 example parses successfully")))
34+
(conformance-valid
35+
. ((command . "cargo run -p anv-cli -- check conformance/valid/*")
36+
(expected . "All valid examples parse and validate without errors")))
37+
(conformance-invalid
38+
. ((command . "for f in conformance/invalid/*; do cargo run -p anv-cli -- check $f 2>&1; done")
39+
(expected . "Each invalid example produces stable diagnostic output")
40+
(count . ">= 5 invalid examples")))))
41+
42+
;; ==========================================================================
43+
;; TASKS (CHECKLIST)
44+
;; ==========================================================================
45+
(tasks
46+
. ((done
47+
. (("Create .machine_read directory")
48+
("Add LLM_SUPERINTENDENT.scm")
49+
("Add SPEC.core.scm")
50+
("Add ROADMAP.f0.scm")
51+
("Add CANONICAL_README.scm")
52+
("Fix STATE.scm language reference")
53+
("Add conformance/valid/ examples (4 files)")
54+
("Add conformance/invalid/ examples (7 files, exceeds >= 5)")
55+
("Mark tree-sitter as optional (OPTIONAL.md)")
56+
("Mark editors as optional (OPTIONAL.md)")
57+
("Verify smoke test passes (152 tests)")
58+
("Verify conformance tests pass")))
59+
(pending
60+
. ())))
61+
62+
;; ==========================================================================
63+
;; SCOPE BOUNDARIES
64+
;; ==========================================================================
65+
(scope
66+
. ((in-scope
67+
. (("Bug fixes in core crates")
68+
("Conformance test additions")
69+
("Documentation corrections")
70+
("Error message improvements")))
71+
(out-of-scope
72+
. (("New language features")
73+
("New crates or binaries")
74+
("Editor/IDE integration work")
75+
("Visualization features")
76+
("IR layer implementation")))))
77+
78+
;; ==========================================================================
79+
;; SUCCESS METRICS
80+
;; ==========================================================================
81+
(success-metrics
82+
. ((tests-passing . ">= 90")
83+
(valid-conformance-files . ">= 3")
84+
(invalid-conformance-files . ">= 5")
85+
(smoke-test-reliable . #t)))
86+
87+
;; ==========================================================================
88+
;; NEXT PHASE
89+
;; ==========================================================================
90+
(next-phase
91+
. ((name . "f1")
92+
(focus . "IR layer and code generation")
93+
(prerequisite . "f0 acceptance criteria met")
94+
(target-tier . "silver")))))

0 commit comments

Comments
 (0)