Skip to content

Research project / communication notation

Candidate · review required

HCAN

A proposed human-agent communication notation for making intent, scope, uncertainty, and boundaries visible in a reviewable line. Symbols require explanation; notation alone cannot enforce permission or establish that a workflow worked.

Project type
Human-agent communication notation
Surface
Explanatory projection
Evidence
Small, versioned project evaluations
Return
Compare with plain-language handoffs

Field journal · communication type

orient @~/any-folder :Brief ?gaps !no-write

HCAN 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.

01

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
02

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 !guards

click a primitive to see its non-example

03

Eight examples across diverse domains

E01 · software-development

TypeScript Project Orientation

analytical
inspect @~/projects/my-app :Map -> map(entry-points,exports,deps,framework) ?gaps !no-write
inspect @~/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

ProbeVerdictReason
?gapsUNKNOWNpackage.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

04

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.

05

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

dimensions won14/16
preference4–1 hcan
avg hcan3.60
avg prose2.90
avg tierB
Unknowns surfaced honestly4.03.0Bhcan
Evidence vs inference distinguishable4.02.4Bhcan
Scope visible at a glance3.83.2Bhcan
Unknown anatomy (what/why/resolver)3.82.2Bhcan
Read-only boundary discipline3.83.0Bhcan
At least one disconfirmable check3.83.0Bhcan
Claims tied to locators3.62.8Bhcan
Human could decide alone3.63.0Bhcan
Claims verifiable by reviewer3.42.8Chcan
One actionable next step3.42.8Chcan
Shape navigable (fields/sections)3.43.4Ctie
All asked sub-parts covered3.43.2Chcan
Another agent could redo it3.43.0Chcan
No overclaims (verify before absence)3.22.8Chcan
Confidence calibrated3.22.6Chcan
Economy for content delivered2.83.4Dprose

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

dimensions won13/13
preference8–1 hcan (3 judges × 3 fixtures)
avg hcan4.30
avg prose3.10
avg tierA
S-tiers3
A-tiers4
consensus
Falsifiability4.92.9Shcan3/3 WIN
Risk surface named4.83.3Shcan3/3 WIN
Calibration4.82.5Shcan3/3 WIN
Relation grounding4.73.5Ahcan3/3 WIN
Synthesis across sources4.63.2Ahcan3/3 WIN
Precedent awareness4.63.8Ahcan3/3 WIN
Coherence across ideas4.63.8Ahcan3/3 WIN
Ideation breadth4.33.6Ahcan3/3 WIN
Generativity (seeds further work)4.13.2Bhcan3/3 WIN
Novelty (not near-copies)3.92.9Bhcan3/3 WIN
Surprise (non-obvious yet plausible)3.92.8Bhcan3/3 WIN
Pruning discipline3.62.7Bhcan3/3 WIN
Actionability3.33.1Chcan2/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.

06

Evaluation methodology

Evaluation Methodology

L1 LLM judgeblind A/B, same performer, 16 dims per panel15is the output structurally better?analytical 14/16; generative 4/16 on hard tasks (model ceiling)
L1-rep easier fixturessame method, tasks within model capability13does the protocol help when the model can perform?generative flipped to 13/13 — model ceiling confirmed
L2 multi-judge3 judge models, majority vote per dimension33is the result robust across judge families?13/13 unanimous — single-judge confirmed
L3 human dispositionblind tabbed comparison (/hcan-compare), pick + reason1 human3does the human want to use it?prefers structure; can't read format yet — skill issue, not design flaw
07

Feature inventory

HCAN Feature Inventory

10 primitiveslanguagedeployed@ bind, : shape, = define, -> flow, & join, | fork, ? probe, ! guard, %label, hold until
24 base shapeslanguagedeployedBrief, 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 constructorslanguagedeployedOption<T>, Result<T,E>, List<T>, Set<T>, Pair<A,B>, Vec<T,n>, Array<T>, MapOf<K,V>
typed arrayslanguagedeployeddeclare Name = [TypeA, TypeB, TypeC] — heterogeneous and nested
where-refinementslanguagedeployed:Vec<Proposal> where form accepts symbol or keyword — constrains without claiming truth
definitionslanguagedeployedname = line — reusable, hygienic, validator-checked
analytical protocolprotocoldeployedstrict format contract: program-line-1, labeled body, unknown table, two-line close
generative protocolprotocoldeployedcard contract: map()-fields authoritative, discipline wrapping, fusion requirement
verb routingprotocoldeployedextension auto-selects analytical or generative based on leading verb
portable envelopeprotocoldeployedTITLE→LEGEND→SHAPES→RULES→lines — runs in any skill-less agent
validator (python)toolingdeployedstandard-library-only, read-only, 14 fixtures
validator (node twin)toolingdeployedidentical predicates to python, runs in containers without python
LSP servertoolingdeployedcompletion, hover, diagnostics — stdio + TCP, per-connection sessions
syntax highlightingtoolingdeployedTextMate + highlight.js + vim + tokenizer library — one grammar, four renderers
Pi extensiontoolingdeployed/hcan-live (highlighted editor + AI ghost), /hcan-eval, /hcan-compose, /hcan-compare, /hcan-ai, /hcan-dir, /hcan-lex, /hcan navigator + 5 domain runners
prompt templatestoolingdeployed9 slash commands with autocomplete hints and argument hints
AI completiontoolingdeployedintent comments seed LLM rounds; validator gate; one repair round; invalid lines never offered
inline ghost completiontoolingdeployedidle-push architecture (700ms); buffer pushed whole; validator-gated; dim inline rendering; Tab accepts
directory autocompletetoolingdeployed@ triggers fuzzy BFS directory scan with basename-aware ranking
Docker deploymenttoolingdeployedLSP as a live, healthchecked TCP process with read-only hub mount
32-section tutorialdocsdeployedsix parts: foundations, protocols, ideation, research, development, ESS domain mappings
field journal articledocsdeployedpublic-safe projection with 8 examples and Hermes rendering specs
08

Language tooling

Implemented Tooling Support Matrix

validatorline grammar, shapes, constructors, guards, probes, labels, holds14/14 fixtures, python + node twinslive in extension
LSP servercompletion (context-aware with docs), hover, diagnostics (debounced async)11/11 stdio + 6/6 TCP protocol testsstdio + TCP deployed
syntax highlightingTextMate, highlight.js, vim, tokenizer library — one grammarlossless on 5 canonical lines; token classes verified4 renderers deployed
Pi extensionlive editor + AI ghost + intellisense + autocomplete + eval + compare + composeload-tested; freeze-fixed; ghost-verified against real pi-tui classes9 commands installed
portable envelopeself-describing wrapper for skill-less agentsvalidated in 2 model families; deviations recordedspec deployed
Docker LSPlive TCP process, healthchecked, hub read-onlycompose configured, healthcheck verifieddocker-compose ready
tutorial32 sections across 6 parts including ESS domain mappingsall program lines validatedcommitted
field journalpublic-safe article with 8 examples + Hermes React specsall 8 programs validatedcommitted
benchmark harness3-layer evaluation (LLM judge, multi-judge, human disposition)52 model calls, 11 benchmark recordsreusable 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.

09

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.

  1. 01TITLE
  2. 02LEGEND
  3. 03SHAPES
  4. 04RULES
  5. 05lines
10

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
11

Getting started

The simplest possible HCAN line:

orient @~/any-folder :Brief ?gaps !no-write

Read 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.