diff --git a/conductor/tracks/intent_dsl_survey_20260612/metadata.json b/conductor/tracks/intent_dsl_survey_20260612/metadata.json new file mode 100644 index 00000000..70074e39 --- /dev/null +++ b/conductor/tracks/intent_dsl_survey_20260612/metadata.json @@ -0,0 +1,24 @@ +{ + "track_id": "intent_dsl_survey_20260612", + "name": "Intent-Based Scripting Languages Survey", + "created": "2026-06-12", + "priority": "A (research)", + "status": "active", + "type": "research-only", + "domain": "Meta-Tooling", + "blocked_by": [], + "deliverable": "docs/ideation/2026-06-12-intent-based-scripting-languages.md", + "consumed_by": [ + "nagent v2.2 (Future-Track Candidate #4: Intent-based DSL)", + "intent_dsl_for_meta_tooling_20260608_PLACEHOLDER (per mcp_architecture_refactor_20260606/spec.md §12.1)", + "future interpreter prototype (follow-up B track)" + ], + "estimated_size": "3500-5000 lines", + "time_sensitive": "Hard boundary for when user can start the next nagent track", + "spec_commit": "b389f1be", + "spec_path": "conductor/tracks/intent_dsl_survey_20260612/spec.md", + "plan_commit": "5ef68a00", + "plan_path": "conductor/tracks/intent_dsl_survey_20260612/plan.md", + "state_path": "conductor/tracks/intent_dsl_survey_20260612/state.toml", + "research_dir": "conductor/tracks/intent_dsl_survey_20260612/research/" +} diff --git a/conductor/tracks/intent_dsl_survey_20260612/state.toml b/conductor/tracks/intent_dsl_survey_20260612/state.toml new file mode 100644 index 00000000..d8d1e232 --- /dev/null +++ b/conductor/tracks/intent_dsl_survey_20260612/state.toml @@ -0,0 +1,64 @@ +# Track state for intent_dsl_survey_20260612 +# Updated by Tier 1 Orchestrator as tasks complete + +[meta] +track_id = "intent_dsl_survey_20260612" +name = "Intent-Based Scripting Languages Survey" +status = "active" +current_phase = 0 +last_updated = "2026-06-12" + +[blocked_by] +# No blockers. Track is independent. + +[phases] +phase_1 = { status = "pending", checkpointsha = "", name = "Source gathering + outline" } +phase_2 = { status = "pending", checkpointsha = "", name = "Write sections 1, 2, 3" } +phase_3 = { status = "pending", checkpointsha = "", name = "Write sections 4, 5, 6, 7" } +phase_4 = { status = "pending", checkpointsha = "", name = "Self-review + user review + commit" } + +[tasks] +t1_1 = { status = "completed", commit_sha = "", description = "Read all 8 prior-art sources end-to-end" } +t1_2 = { status = "in_progress", commit_sha = "", description = "Create state.toml + metadata.json" } +t1_3 = { status = "pending", commit_sha = "", description = "Write 7-section outline stub" } +t1_4 = { status = "pending", commit_sha = "", description = "Phase 1 checkpoint commit" } +t2_1 = { status = "pending", commit_sha = "", description = "Write section 1 (philosophy)" } +t2_2 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 0 (O'Donnell)" } +t2_3 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 1 (Concatenative)" } +t2_4 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 2 (Array)" } +t2_5 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 3 (Intent-mapping)" } +t2_6 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 4 (Meta-Tooling DSLs)" } +t2_7 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 5 (SSDL)" } +t2_8 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 6 (Command Palette)" } +t2_9 = { status = "pending", commit_sha = "", description = "Write section 2 cluster 7 (Result)" } +t2_10 = { status = "pending", commit_sha = "", description = "Write section 3 (grammar)" } +t2_11 = { status = "pending", commit_sha = "", description = "Phase 2 checkpoint commit" } +t3_1 = { status = "pending", commit_sha = "", description = "Write section 4 Tier 1 (math)" } +t3_2 = { status = "pending", commit_sha = "", description = "Write section 4 Tier 2 (data pipeline)" } +t3_3 = { status = "pending", commit_sha = "", description = "Write section 4 Tier 3 (shell)" } +t3_4 = { status = "pending", commit_sha = "", description = "Write section 4 Tier 4 (AI-fuzzing tolerance)" } +t3_5 = { status = "pending", commit_sha = "", description = "Write section 5 (hardware mapping)" } +t3_6 = { status = "pending", commit_sha = "", description = "Write section 6 (AI-agent properties)" } +t3_7 = { status = "pending", commit_sha = "", description = "Write section 7 (open questions)" } +t3_8 = { status = "pending", commit_sha = "", description = "Phase 3 checkpoint commit" } +t4_1 = { status = "pending", commit_sha = "", description = "Self-review per brainstorming skill" } +t4_2 = { status = "pending", commit_sha = "", description = "User review" } +t4_3 = { status = "pending", commit_sha = "", description = "Apply user feedback (if any)" } +t4_4 = { status = "pending", commit_sha = "", description = "Final commit + git note" } +t4_5 = { status = "pending", commit_sha = "", description = "Update tracks.md to register track as completed" } + +[verification] +phase_1_complete = false +phase_2_complete = false +phase_3_complete = false +phase_4_complete = false +all_7_sections_present = false +all_prior_art_cited = false +all_4_tier_verbs_complete = false +hardware_mapping_referenced = false +ai_agent_properties_referenced = false +section_7_has_6_open_questions = false +self_review_complete = false +user_approved = false +git_note_attached = false +tracks_md_registered = false diff --git a/docs/ideation/2026-06-12-intent-based-scripting-languages.md b/docs/ideation/2026-06-12-intent-based-scripting-languages.md new file mode 100644 index 00000000..7e1a638a --- /dev/null +++ b/docs/ideation/2026-06-12-intent-based-scripting-languages.md @@ -0,0 +1,113 @@ +# Intent-Based Scripting Languages + +**Track:** `intent_dsl_survey_20260612` (initialized 2026-06-12) +**Date:** 2026-06-12 +**Author:** Tier 1 Orchestrator (sections 1, 3, 4, 5, 6, 7, Appendix); Tier 2 sub-agents (section 2 clusters 0, 1, 2, 3, 4) +**Status:** Outline draft (phase 1 of 4) + +> **What this is.** A survey of intent-based scripting languages as a design philosophy, plus a proposed vocabulary (~40 verbs across 4 tiers) for a Meta-Tooling-facing intent DSL. The report is the foundation document for the user's nagent v2.2 (its "Future-Track Candidate #4" section) and for the future interpreter prototype (follow-up B track). +> +> **What this is NOT.** Not an interpreter, not a bridge script, not Application-side function-calling, not XML/JSON record formats. The DSL is Meta-Tooling-side per `docs/guide_meta_boundary.md` — the format external agents (Gemini CLI, OpenCode) emit when invoking `mcp_client.py` tools. + +--- + +## 1. The "Intent-Based" Design Philosophy + +*[STUB: 4 anchor claims — O'Donnell immediate-mode as the philosophical anchor; Onat/Lottes hardware-pipeline model as the truth the verbs must map to; CoSy open-vocabulary culture as the user-surface principle; Jofito intent-mapping as the framing that names the design philosophy. ~2-3 pages.]* + +## 2. Prior Art Survey (8 Clusters) + +This section surveys the design lineage across 8 clusters. Each entry: 2-3 sentences on the design idea, 2-3 sentences on what we take from it (or, in cluster 3, what we explicitly reject). Every entry cites a specific source. + +### Cluster 0 — Immediate-Mode Paradigm (philosophical anchor) +*[STUB: John O'Donnell's IMGUI/MVC essays. ~0.5-1 page.]* + +### Cluster 1 — Concatenative (Forth family) +*[STUB: Forth, ColorForth, KYRA/Onat, x68/Lottes, Joy, CoSy. ~1-1.5 pages.]* + +### Cluster 2 — Array +*[STUB: APL, K, BQN, Uiua. ~0.5 page.]* + +### Cluster 3 — Intent-Mapping +*[STUB: Jofito, jq, nagent's tag protocol (REJECTED as a model — we take the structured-protocol idea but not the XML angle brackets), Wasm. ~0.5-1 page.]* + +### Cluster 4 — Meta-Tooling DSLs and Agent-Facing Languages +*[STUB: mcp_dsl_20260606 placeholder, nagent's Bridge DSL, OpenAI function-calling, Anthropic tool-use. ~0.5 page.]* + +### Cluster 5 — SSDL Shape Primitives +*[STUB: 6 primitives + 7 modifiers per `docs/reports/computational_shapes_ssdl_digest_20260608.md` §1. The meta-vocabulary used to annotate the verbs in section 4. ~0.25 page.]* + +### Cluster 6 — Project's Own Command DSL Precedents +*[STUB: the 33 Command Palette commands per `docs/guide_command_palette.md` and `src/commands.py`. The DSL is a richer superset; "Everything" mode is a near-term use case. ~0.25 page.]* + +### Cluster 7 — Data-Oriented Error Handling Convention +*[STUB: `Result[T]` + `ErrorInfo` per `conductor/tracks/data_oriented_error_handling_20260606/spec.md` §3.3. The DSL's `try`/`recover`/`sandbox`/`didyoumean` verbs return `Result[T]`. ~0.25 page.]* + +## 3. The Grammar + +*[STUB: 14 primitives formalized from the user's math pseudocode (`determinate`/`minor`/`matrix-transpose` snippets). Each primitive: symbol, name, signature, one-line semantics, example, "borrowed from" note. Plus 3 known ambiguity flags (`proc` placement, `++` → `+= 1`, `m[row][column]` → `m[row, col]`). Plus precedence rules (left-to-right for `->` chains, `()` for grouping) and AI-fuzzing tolerance rules (CoSy-style modulo indexing, structured recovery anchors via `{}`, line/offset independence). Plus the error envelope (`try { ... } recover { ... }` returns `Result[T]`). ~2-3 pages.]* + +## 4. The 4-Tier Vocab (~40 Verbs) + +Each verb: symbol, name, signature, one-line semantics, one example, "borrowed from" note, SSDL shape tag. Tier 2 and Tier 3 verbs also have a "maps to mcp_client tool" column. + +### Tier 1 — Math (~10 verbs) +*[STUB: from the user's pseudocode. `:=`, `stack { }`, `for x .. n`, `+`, `-`, `*`, `/`, `^`, `sum`, `product`, `a[i,j]`, `if/then`.]* + +### Tier 2 — Data-Oriented Pipeline (~12 verbs) +*[STUB: Onat/Lottes/Jofito lineage. `scan`, `select`, `filter`, `map`, `fold`, `sort`, `group`, `dedupe`, `arena { }`, `scatter`, `gather`, `pipe`. The verbs that wrap the existing 45+ MCP tools.]* + +### Tier 3 — Shell (~10 verbs) +*[STUB: the OS surface. `exec`, `open`, `read`, `write`, `close`, `path`, `env`, `wait`, `poll`, `cwd`.]* + +### Tier 4 — AI-Fuzzing Tolerance (~8 verbs — the novel contribution) +*[STUB: the verbs that make the DSL work for AI agents that may fuzz verb names, indent inconsistently, or offset line references. `fuzzy`, `try { ... } recover { ... }`, `sandbox { ... }`, `audit`, `didyoumean`, `span`, `offset`, `assumewide`. The `sandbox` verb is O'Donnell's IEventTarget pattern applied to the DSL; the `audit` verb is the IEventTarget itself.]* + +## 5. Hardware Mapping (4 Anchor Claims) + +*[STUB: 4 anchor claims tying the vocab to actual hardware/software stages.* + +1. **Onat/Lottes, hardware:** the 2-register stack + magenta pipe + basic blocks + lambdas + preemptive scatter (per `C:\projects\forth\bootslop\references\kyra_in-depth.md`, `forth_day_2020_in-depth.md`, `neokineogfx_in-depth.md`, `X.com - Onat & Lottes Interaction 1.png.ocr.md`) → our `->`, `[ ]`, `arena { }`, `scatter`/`gather`. +2. **O'Donnell, paradigm:** the DSL's pipeline is *immediate-mode in pipeline composition*. Per `https://johno.se/book/imgui.html`. The `->` chain has no "pipeline object" you can query, name, or pass around. +3. **Forth/CoSy, syntax:** concatenative syntax is immediate-mode in tokenization (whitespace-delimited, no precedence), evaluation (each verb pops args, pushes results), and parsing (no AST object retained after parse). +4. **APL/K, data:** array languages are immediate-mode in data representation. The DSL's `for x .. n` + `result[row, col]` inherits the "no array object" property. + +*~1-2 pages.]* + +## 6. AI-Agent Properties (10 Claims) + +*[STUB: 10 claims tying the DSL to the existing project's architecture so future tracks can build on it without re-deriving the design.* + +1. Domain = Meta-Tooling (per `docs/guide_meta_boundary.md`). +2. Runtime path = external agent → DSL text → bridge script → MCP → optional Hook API approval (per `docs/guide_meta_boundary.md` §"The Inter-Domain Bridges"). +3. 3-layer security (per `docs/guide_tools.md` §"The MCP Bridge"): the parser rejects DSL statements that target tools outside the allowlist. +4. 4 memory dimensions (per `conductor/tracks/nagent_review_20260608/nagent_review_v2_1_20260612.md` §2.1): the DSL does not replace any memory dimension. +5. Stable-to-volatile cache ordering (per nagent v2.1 §2.2): the DSL's `arena { }` blocks are cache-friendly. +6. `Result[T]` envelope (per `conductor/tracks/data_oriented_error_handling_20260606/spec.md`): `try`/`recover` verbs return `Result[T]`. +7. Command Palette 33 commands (per `docs/guide_command_palette.md`): the DSL is a richer superset; "Everything" mode is a near-term use case. +8. Hook API state fields (per `docs/guide_state_lifecycle.md` §"Hook API Surface"): DSL verbs route through `_predefined_callbacks` and `_gettable_fields`. +9. O'Donnell's IEventTarget pattern as the `sandbox` verb (per `https://johno.se/book/mvc.html` §"Writing to Model state"). +10. O'Donnell's "reads are free" claim (per `https://johno.se/book/mvc.html` §"Reading Model state"): Tier 2 verbs are read-only and re-evaluable. + +*~2-3 pages.]* + +## 7. Open Questions for Follow-up B (≥6) + +*[STUB: open questions that the follow-up B track (interpreter prototype) must answer, plus the connection block to the `intent_dsl_for_meta_tooling_20260608_PLACEHOLDER`.* + +1. How does `arena { }` map to Onat's preemptive scatter? Block-as-tape vs wrapper-allocates-tape? +2. Where does "intent resolution" live? Per-verb option, per-block modifier, or global parser mode? +3. How does `audit` interact with Manual Slop's existing `comms.log`? Separate JSON-L or merged? +4. Does `sandbox` produce `Result[T, ErrorInfo]` (Fleury pattern)? +5. `didyoumean` recovery: parser feature or user-facing verb? +6. How does `for x .. n` interact with Tier 2's `filter`/`map`? Sugar or distinct? +7. How does `sandbox` map to Manual Slop's `pre_tool_callback` flow? New audit log or fold into existing? +8. Connection to `intent_dsl_for_meta_tooling_20260608_PLACEHOLDER`: minimum vocab subset for one round-trip end-to-end? + +*~1-2 pages.]* + +--- + +## Appendix: Bibliography + +*[STUB: full file:line / URL references for all 8 prior-art clusters + the project's own references. Grouped by cluster. Each entry: 1 line with the source identifier and the file:line or URL.]*