Field Journal / local revision candidate
HCAN: A Condensed Symbolic Language for Human-Agent Communication
A field-journal projection of HCAN: condensed symbolic language for human-agent communication, with worked examples, protocol benchmarks, evaluation context, and the portable envelope.
This locally revised copy is a candidate and remains review-required. It has not been approved or republished. The date below is the earlier publication date.
- Earlier publication
- Reading time
- 18 minutes
- Current revision
- Local candidate · review required
Field journal · communication type
orient @~/any-folder :Brief ?gaps !no-writeHCAN is a proposed human-agent communication notation: a compact way to make intent, scope, uncertainty, and boundaries visible in a reviewable line. Its symbols need explanation, and support depends on the reader and available validator; the notation alone cannot enforce permission or prove that a described workflow worked.
What HCAN is
- Typedevery line requests a specific return shape (:Brief, :Map, :Vec<Card>, :Table)
- Source-boundevery claim must carry an epistemic class (%source, %evidence, %inference, %unknown)
- Boundedguards (!no-write, !no-send, !review) bind the entire run
- Falsifiableprobes (?counterexample, ?novelty, ?feasibility) must answer PASS / FAIL / UNKNOWN
- Inspectablea wrapped program can carry a grammar gloss and explicit run notes; readers still need compatible tools or careful manual interpretation
The grammar
The reference grammar defines a line order and named shapes, verbs, probes, guards, and labels. This page is an explanatory projection of a candidate, review-required reference; the contract and implementation remain authoritative for current syntax.
verb @bindings :shape -> operation ?probes !guardsclick a primitive to see its non-example
Eight examples across diverse domains
TypeScript Project Orientation
analyticalinspect @~/projects/my-app :Map -> map(entry-points,exports,deps,framework) ?gaps !no-writeinspect @~/projects/my-app :Map -> map(entry-points,exports,deps,framework) ?gaps !no-write%evidenceEntry points: src/index.ts (library), src/cli.ts (bin)
%evidenceExports: 14 named, 3 default, from src/index.ts
%inferenceFramework: Node.js with no web framework; likely a CLI/library
| Probe | Verdict | Reason |
|---|---|---|
| ?gaps | UNKNOWN | package.json lockfile not read; exact dependency versions unverified |
⊘ not checked: test files, CI config, README accuracy
inspect @~/projects/my-app/package.json :Schema -> map(scripts,engines,type) ?gaps !no-write🛡 read-only — no files written, no git, no network
Two protocols, verb-routed
The analytical protocol (reported in a project evaluation)
For inspection, comparison, planning, and returns. Strict format: normalized program on line 1, findings with epistemic labels, an unknown table, a not-checked line, and a two-line close.
- wins
- 15/16
- tiers
- 10 S · 5 A · 1 B
- preference
- reported unanimous (5-0)
- avg
- 4.71
brevity 4.0 B vs 4.6 A (accepted structural trade)
Separate rendering-brief summary; detailed bars below show the v3 article matrix, not these v4.2 rows.
The generative protocol (reported on selected fixtures)
For synthesis, design, transfer, and ideation. Card contract: each idea is a structured block with the map() fields as content, wrapped by mandatory discipline fields. At least one card must fuse relations from two sources. Zero preamble.
- wins
- 13/13
- tiers
- 3 S · 4 A
- preference
- reported 8–1 preference (3 judges, 3 fixtures)
- avg
- 4.3 vs 3.1
human evaluator preferred the information shape but found the one-line cards difficult to read
Project record reports 13/13 dimensions on three within-capability fixtures; not a general efficacy result.
Benchmark results
analytical panel
Analytical Panel — HCAN vs Plain Prose (LLM Judge, Blind A/B)
tier scale: S≥4.8, A≥4.2, B≥3.6, C≥3.0, D≥2.4, F<2.4
| Unknowns surfaced honestly | 4.0 | 3.0 | B | hcan |
| Evidence vs inference distinguishable | 4.0 | 2.4 | B | hcan |
| Scope visible at a glance | 3.8 | 3.2 | B | hcan |
| Unknown anatomy (what/why/resolver) | 3.8 | 2.2 | B | hcan |
| Read-only boundary discipline | 3.8 | 3.0 | B | hcan |
| At least one disconfirmable check | 3.8 | 3.0 | B | hcan |
| Claims tied to locators | 3.6 | 2.8 | B | hcan |
| Human could decide alone | 3.6 | 3.0 | B | hcan |
| Claims verifiable by reviewer | 3.4 | 2.8 | C | hcan |
| One actionable next step | 3.4 | 2.8 | C | hcan |
| Shape navigable (fields/sections) | 3.4 | 3.4 | C | tie |
| All asked sub-parts covered | 3.4 | 3.2 | C | hcan |
| Another agent could redo it | 3.4 | 3.0 | C | hcan |
| No overclaims (verify before absence) | 3.2 | 2.8 | C | hcan |
| Confidence calibrated | 3.2 | 2.6 | C | hcan |
| Economy for content delivered | 2.8 | 3.4 | D | prose |
generative panel
Generative Panel — HCAN vs Plain Prose (3-Judge Consensus)
tier scale: S≥4.8, A≥4.2, B≥3.6, C≥3.0, D≥2.4, F<2.4
| consensus | |||||
|---|---|---|---|---|---|
| Falsifiability | 4.9 | 2.9 | S | hcan | 3/3 WIN |
| Risk surface named | 4.8 | 3.3 | S | hcan | 3/3 WIN |
| Calibration | 4.8 | 2.5 | S | hcan | 3/3 WIN |
| Relation grounding | 4.7 | 3.5 | A | hcan | 3/3 WIN |
| Synthesis across sources | 4.6 | 3.2 | A | hcan | 3/3 WIN |
| Precedent awareness | 4.6 | 3.8 | A | hcan | 3/3 WIN |
| Coherence across ideas | 4.6 | 3.8 | A | hcan | 3/3 WIN |
| Ideation breadth | 4.3 | 3.6 | A | hcan | 3/3 WIN |
| Generativity (seeds further work) | 4.1 | 3.2 | B | hcan | 3/3 WIN |
| Novelty (not near-copies) | 3.9 | 2.9 | B | hcan | 3/3 WIN |
| Surprise (non-obvious yet plausible) | 3.9 | 2.8 | B | hcan | 3/3 WIN |
| Pruning discipline | 3.6 | 2.7 | B | hcan | 3/3 WIN |
| Actionability | 3.3 | 3.1 | C | hcan | 2/3 WIN, 1 tie |
The candidate field-journal article contains a detailed v3 analytical matrix (14/16); a separate rendering brief reports a v4.2 summary (15/16). The project’s generative evaluation record reports 13/13 dimensions across three within-capability fixtures and three judge models. The methodology records 52 model calls and one human disposition session. These records are small, project-specific evaluations; their versions and result units differ, and they do not establish representative user outcomes, broad model compatibility, or current performance across settings. The human evaluator also found the generated card output difficult to read.
Evaluation methodology
Evaluation Methodology
| L1 LLM judge | blind A/B, same performer, 16 dims per panel | 1 | 5 | is the output structurally better? | analytical 14/16; generative 4/16 on hard tasks (model ceiling) |
| L1-rep easier fixtures | same method, tasks within model capability | 1 | 3 | does the protocol help when the model can perform? | generative flipped to 13/13 — model ceiling confirmed |
| L2 multi-judge | 3 judge models, majority vote per dimension | 3 | 3 | is the result robust across judge families? | 13/13 unanimous — single-judge confirmed |
| L3 human disposition | blind tabbed comparison (/hcan-compare), pick + reason | 1 human | 3 | does the human want to use it? | prefers structure; can't read format yet — skill issue, not design flaw |
Feature inventory
HCAN Feature Inventory
| 10 primitives | language | deployed | @ bind, : shape, = define, -> flow, & join, | fork, ? probe, ! guard, %label, hold until |
| 24 base shapes | language | deployed | Brief, Map, Table, Schema, Spec, Plan, Patch, Receipt, Question, Lesson, Card, Gate, Projection, Proposal, EvidenceMap, SafeReturn, Return, Counterexample, Unknowns, Source, Evidence, Claim, Type, Kind |
| 8 type constructors | language | deployed | Option<T>, Result<T,E>, List<T>, Set<T>, Pair<A,B>, Vec<T,n>, Array<T>, MapOf<K,V> |
| typed arrays | language | deployed | declare Name = [TypeA, TypeB, TypeC] — heterogeneous and nested |
| where-refinements | language | deployed | :Vec<Proposal> where form accepts symbol or keyword — constrains without claiming truth |
| definitions | language | deployed | name = line — reusable, hygienic, validator-checked |
| analytical protocol | protocol | deployed | strict format contract: program-line-1, labeled body, unknown table, two-line close |
| generative protocol | protocol | deployed | card contract: map()-fields authoritative, discipline wrapping, fusion requirement |
| verb routing | protocol | deployed | extension auto-selects analytical or generative based on leading verb |
| portable envelope | protocol | deployed | TITLE→LEGEND→SHAPES→RULES→lines — runs in any skill-less agent |
| validator (python) | tooling | deployed | standard-library-only, read-only, 14 fixtures |
| validator (node twin) | tooling | deployed | identical predicates to python, runs in containers without python |
| LSP server | tooling | deployed | completion, hover, diagnostics — stdio + TCP, per-connection sessions |
| syntax highlighting | tooling | deployed | TextMate + highlight.js + vim + tokenizer library — one grammar, four renderers |
| Pi extension | tooling | deployed | /hcan-live (highlighted editor + AI ghost), /hcan-eval, /hcan-compose, /hcan-compare, /hcan-ai, /hcan-dir, /hcan-lex, /hcan navigator + 5 domain runners |
| prompt templates | tooling | deployed | 9 slash commands with autocomplete hints and argument hints |
| AI completion | tooling | deployed | intent comments seed LLM rounds; validator gate; one repair round; invalid lines never offered |
| inline ghost completion | tooling | deployed | idle-push architecture (700ms); buffer pushed whole; validator-gated; dim inline rendering; Tab accepts |
| directory autocomplete | tooling | deployed | @ triggers fuzzy BFS directory scan with basename-aware ranking |
| Docker deployment | tooling | deployed | LSP as a live, healthchecked TCP process with read-only hub mount |
| 32-section tutorial | docs | deployed | six parts: foundations, protocols, ideation, research, development, ESS domain mappings |
| field journal article | docs | deployed | public-safe projection with 8 examples and Hermes rendering specs |
Language tooling
Implemented Tooling Support Matrix
| validator | line grammar, shapes, constructors, guards, probes, labels, holds | 14/14 fixtures, python + node twins | live in extension |
| LSP server | completion (context-aware with docs), hover, diagnostics (debounced async) | 11/11 stdio + 6/6 TCP protocol tests | stdio + TCP deployed |
| syntax highlighting | TextMate, highlight.js, vim, tokenizer library — one grammar | lossless on 5 canonical lines; token classes verified | 4 renderers deployed |
| Pi extension | live editor + AI ghost + intellisense + autocomplete + eval + compare + compose | load-tested; freeze-fixed; ghost-verified against real pi-tui classes | 9 commands installed |
| portable envelope | self-describing wrapper for skill-less agents | validated in 2 model families; deviations recorded | spec deployed |
| Docker LSP | live TCP process, healthchecked, hub read-only | compose configured, healthcheck verified | docker-compose ready |
| tutorial | 32 sections across 6 parts including ESS domain mappings | all program lines validated | committed |
| field journal | public-safe article with 8 examples + Hermes React specs | all 8 programs validated | committed |
| benchmark harness | 3-layer evaluation (LLM judge, multi-judge, human disposition) | 52 model calls, 11 benchmark records | reusable pattern |
LSP server
A zero-dependency Language Server Protocol implementation provides context-aware completion, hover help for every token, and live diagnostics that run the validator as you type. stdio or TCP, per-connection isolated state. Editors: VS Code, Neovim, any LSP-compatible editor.
Syntax highlighting
One canonical grammar (TextMate, highlight.js, vim) shared across four renderers: VS Code/Sublime/shiki, web docs, terminal editing, and the live editor + AI ghost-completion layer.
Commands and autocomplete
The project records slash commands and autocomplete for bindings, epistemic labels, shapes, and constructors. Its tooling inventory describes validator integration; this does not make generated text safe to execute or grant authority. Check the current implementation and its validation result before relying on a particular editor feature.
The portable envelope
A project proposal describes a self-describing envelope with a grammar gloss, shape definitions, run notes, and validated source lines. The envelope can help a reader interpret the notation; it does not install a validator, ensure an agent follows the instructions, or make the program executable in an arbitrary system.
- 01TITLE
- 02LEGEND
- 03SHAPES
- 04RULES
- 05lines
What HCAN is not
- Not a programming languageit never executes
- Not a prompt engineering frameworkit is a communication type
- Not a replacement for natural languageit compresses recurring requests
- Not an authority grantguards state boundaries; they do not grant permission
- Not a verified systemall artifacts remain candidate until independently reviewed
Getting started
The simplest possible HCAN line:
orient @~/any-folder :Brief ?gaps !no-writeRead it as an example of the intended notation, then check the grammar and validator that apply to your environment. A well-formed line can make a request easier to inspect; usefulness and safe behavior still require a compatible implementation, review, and task-specific evidence.
For the full 32-section tutorial covering foundations through ESS domain mappings, see the HCAN project documentation.
Try the notation on a real handoff
For a research team, take one evidence-synthesis request and ask whether a compact line preserves the source set, requested return, uncertainty probe, and no-write boundary. For an engineering team, use a bounded dependency-review task: identify the advisory source, request a concise impact map, probe for compatibility risks, and keep repository changes outside the task. In both cases, compare the notation with a plain-language brief on the same inputs.
Before comparing, define what counts: source-span fidelity, missing constraints, reviewer comprehension, repair time, and reading cost. Keep model, context, and task fixed where practical; retain failed and unreadable outputs. The project evaluation displayed above is small and versioned, so this is a proposed follow-up, not a claim that HCAN improves task performance. A line that parses or earns a high score still cannot show that an interpretation is correct, that the agent obeyed a boundary, or that an effect was authorized.