# Human-Computer Mutual Legibility — FULL RESEARCH CORPUS Abbreviation: hcml Version: v2.0.0 | Generated: unspecified | Files: 31 | Lines: 4,593 | Payload: 204.1 KiB Source path: /Users/zachshallbetter/Projects/_protocols/human-computer-mutual-legibility Bundle name: llm-full-docs-hcml Corpus Payload SHA-256: 2854b640b39398fb87d53155e9dda651a4f83a71376f1dd421eb23a23c1e7015 TABLE OF CONTENTS: - .agents/AGENTS.md (67 lines, 3.1 KiB) - HCML-Relationship-State-Extension/08-open-gaps-and-missing-theory.md (177 lines, 8.2 KiB) - HCML-Relationship-State-Extension/09-relationship-state-model.md (167 lines, 6.7 KiB) - HCML-Relationship-State-Extension/10-temporal-consistency-correction-and-forgetting.md (159 lines, 7.1 KiB) - HCML-Relationship-State-Extension/11-plural-actors-delegation-and-opacity.md (155 lines, 7.1 KiB) - HCML-Relationship-State-Extension/12-typed-uncertainty-and-disagreement.md (134 lines, 5.5 KiB) - HCML-Relationship-State-Extension/13-relationship-state-threat-model.md (155 lines, 6.5 KiB) - HCML-Relationship-State-Extension/14-measurement-and-empirical-validation-program.md (187 lines, 8.8 KiB) - HCML-Relationship-State-Extension/15-relationship-state-research-roadmap.md (154 lines, 7.2 KiB) - HCML-Relationship-State-Extension/README.md (35 lines, 2.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/00-program-charter.md (174 lines, 7.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/01-theory-of-mutual-legibility.md (178 lines, 7.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/02-evidence-across-implementations.md (208 lines, 10.0 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/03-shared-computational-model-architecture.md (230 lines, 9.2 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/04-mutual-interaction-authority-protocol.md (196 lines, 8.1 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/05-research-validation-program.md (213 lines, 9.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/06-publication-framework.md (187 lines, 7.8 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/07-design-principles-implementation-heuristics.md (193 lines, 8.3 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/08-open-gaps-and-missing-theory.md (177 lines, 8.2 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/09-relationship-state-model.md (167 lines, 6.7 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/10-temporal-consistency-correction-and-forgetting.md (159 lines, 7.1 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/11-plural-actors-delegation-and-opacity.md (155 lines, 7.1 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/12-typed-uncertainty-and-disagreement.md (134 lines, 5.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/13-relationship-state-threat-model.md (155 lines, 6.5 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/14-measurement-and-empirical-validation-program.md (187 lines, 8.8 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/15-relationship-state-research-roadmap.md (154 lines, 7.2 KiB) - Human-Computer-Mutual-Legibility-Research-Corpus-v2/README.md (35 lines, 2.5 KiB) - LICENSE (21 lines, 1.0 KiB) - README.md (64 lines, 6.0 KiB) - package.json (8 lines, 0.5 KiB) - scripts/gen-llms.py (208 lines, 6.5 KiB) ======================================================================== ======================================================================== ## FILE: .agents/AGENTS.md (67 lines, 3.1 KiB) ======================================================================== # Human–Computer Mutual Legibility (HCML) Agent Operating Contract (`.agents/AGENTS.md`) This document defines the system doctrine, operational guidelines, status honesty rules, hierarchy of authority, verification gates, and engineering standards governing AI agents and human collaborators working on **Human–Computer Mutual Legibility (HCML)**. --- ## 1. System Taxonomy & Canonical Naming Agents must consistently enforce official naming across code, documentation, and commit messages: ```text Human–Computer Mutual Legibility (HCML) ├── Research Corpus v2 (Human-Computer-Mutual-Legibility-Research-Corpus-v2/) │ ├── 00-07 Core Mutual Legibility Framework │ └── 08-15 Relationship State Model & Research Roadmap └── Relationship State Extension (HCML-Relationship-State-Extension/) ``` --- ## 2. Epistemic Integrity & "Status Honesty" Rules Agents must adhere strictly to the **Four-Tier Claim Taxonomy**: $$\text{Documented} \neq \text{Implemented} \neq \text{Tested} \neq \text{Empirically Validated}$$ 1. **Never Conflate Maturity Levels**: - A hypothesis or model described in the research corpus is *documented*, not *implemented*. - Mechanism prototypes are *tested*, not *empirically validated*. State the weaker claim when in doubt. 2. **Permanent Retention of Negative Results**: - Open gaps, missing theory, threat models, and disproven interaction patterns are preserved permanently in `08-open-gaps-and-missing-theory.md` and `13-relationship-state-threat-model.md`. 3. **Core Invariant**: - HCML describes an engineered condition of reciprocal legibility for intent, evidence, authority, and uncertainty. It does not imply mutual consciousness or equal agency. --- ## 3. Hierarchy of Authority When documentation, code, generated artifacts, or AI outputs conflict, resolve in strict canonical order: $$\text{Program Charter & Theory (00-01)} \to \text{Computational & Interaction Model (03-04)} \to \text{Relationship State Extension (08-15)} \to \text{Reference Implementation} \to \text{Generated Artifacts}$$ - **Rule**: Generated artifacts **never** silently alter canonical research specifications. --- ## 4. Verification Gates & Execution Standard Before proposing modifications or additions to the research corpus, run the context exporter script: ```bash python3 scripts/gen-llms.py ``` ### Verification Rules - **Git Voice**: Use clean, human engineering prose. No AI attribution trailers (`Co-Authored-By`, `Generated by AI`), no tool session IDs in tracked commits or docs. --- ## 5. Agent-First Publishing Architecture (`.agents/llms-full-hcml-v0.2.0.txt`) 1. **Single-Pass Deterministic Context (`llms-full-hcml-v0.2.0.txt`)**: - `.agents/llms-full-hcml-v0.2.0.txt` is an auto-generated, single-file concatenation of the entire 16-chapter research corpus and extension specifications. - Reading `llms-full-hcml-v0.2.0.txt` provides AI agents with instant, zero-search access to all HCML theory and specs without multi-step file discovery latency. 2. **Automated Downstream Generation**: - Generated via `python3 scripts/gen-llms.py`. ======================================================================== ## FILE: HCML-Relationship-State-Extension/08-open-gaps-and-missing-theory.md (177 lines, 8.2 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Open Gaps and Missing Theory What remains unresolved after the first HCML formulation Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The largest unresolved problem is not representation. It is deciding what may legitimately become relationship state, who may establish it, how long it remains valid, and how disagreement survives without being silently resolved.** # 1. Gap map ----------------------------------------------------------------------- **Gap** **Why it matters** **Failure if ignored** ----------------------- ----------------------- ----------------------- Represented intent A human utterance is System upgrades evidence about intent, interpretation into not intent itself. authority. Legibility vs agreement Understanding does not System treats require convergence. disagreement as failure to align. Distributed machine LLM, compiler, Machine prose is state database, policy engine mistaken for system and runtime may truth. disagree. Legibility bandwidth Complete transparency Technically inspectable can overwhelm. but practically unusable systems. Temporal consistency Intent, interpretation Agent faithfully and execution evolve at executes stale intent. different times. Correction economics Repair can become more Human becomes permanent burdensome than the supervisor. original work. Typed uncertainty Confidence is not one Probabilities, source thing. quality and human confidence collapse into one number. Delegation topology Authority varies by Permissions become too action, risk, coarse to encode real reversibility and responsibility. actor. Shared-model security The relationship model Provenance, authority becomes a high-value or acceptance can be target. forged. Plural humans There is rarely one Operator preference human interest or erases affected authority. stakeholders. Absent stakeholders Affected people may not Coherent interaction be participants. remains unjust or incomplete. Behavior vs intent Observed behavior is System infers intention not self-interpreting. from hesitation, clicks or abandonment. Right to opacity Some human state should Mutual legibility remain tentative, becomes compulsory private or uncommitted. legibility. Forgetting Persistent memory can Stale assumptions gain preserve obsolete or durable authority. revoked state. Success criteria Legibility is not Theory becomes valuable merely because unfalsifiable interface it exists. rhetoric. ----------------------------------------------------------------------- # 2. Central correction to the original model NOT:\ Human Model \<-\> Shared Model \<-\> Machine Model\ \ MORE PRECISELY:\ Human state(s) \> Relationship State \<\ Machine state(s) /\ \ The shared object is not a merged mind.\ It is the explicit computational state of the relationship. +-----------------------------------------------------------------------+ | **Primary refinement** | | | | HCML should optimize for inspectable difference and correctable | | relationship state, not for making human and machine internal models | | converge. | +=======================================================================+ +-----------------------------------------------------------------------+ # 3. Hard boundaries - Human state represented in the system must always have source and authority provenance. - Machine assertions must be distinguishable from machine observations and machine authority. - Unknown, unresolved, disagreed, revoked, hidden, absent and unauthorized are distinct states. - Human-facing claims require human evidence; architectural representability is not behavioral validation. - A relationship state may coordinate actors without claiming to contain their complete beliefs, motives or understanding. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/09-relationship-state-model.md (167 lines, 6.7 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship State Model The explicit computational state of a human--computer relationship Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **Relationship State is the proposed central primitive: a versioned, scoped, provenance-bearing record of what was asked, understood, permitted, inferred, evidenced, executed, corrected, accepted, revoked, and left unresolved between participants.** # 1. Formal shape RelationshipState {\ scope\ participants\[\]\ intentRepresentations\[\]\ interpretations\[\]\ constraints\[\]\ authorityGrants\[\]\ evidence\[\]\ uncertainty\[\]\ disagreements\[\]\ commitments\[\]\ candidateActions\[\]\ executions\[\]\ observations\[\]\ corrections\[\]\ revocations\[\]\ unresolved\[\]\ history\ version\ } # 2. State classes ----------------------------------------------------------------------- **Class** **Meaning** **Who may establish** ----------------------- ----------------------- ----------------------- Declared Explicitly stated and Named human/system committed by an authority. authorized participant. Inferred System interpretation Inference mechanism; or model-derived never self-promotes. conclusion. Observed Recorded event or state Observation authority. from an authoritative sensor/tool/runtime. Contract-relative True only under a Contract authority. declared comparison, policy or project contract. Candidate Proposed but not Any permitted proposer. accepted as governing state. Accepted Accepted for a bounded Acceptance authority. scope. Committed Frozen or Commit authority. execution-governing state. Revoked Formerly active but no Revocation authority. longer authorized. Unresolved Material difference not No one; it is yet adjudicated. explicitly retained. Historical-only Preserved for Lifecycle policy. provenance but excluded from current decision state. ----------------------------------------------------------------------- # 3. Relationship state is scoped The same person and same computational system may have different relationship states simultaneously. Authority, memory, persistence, privacy, and acceptable automation are properties of the relationship context, not global properties of either participant. Project A: AI may modify source but may not deploy.\ Project B: AI is read-only.\ Decision C: AI may advise but human owns weights and exit.\ Private conversation: no durable project state unless explicitly promoted. # 4. Invariants - No inference silently becomes declared human intent. - No capability silently becomes authority. - No observation automatically becomes interpretation. - No machine output self-promotes from candidate to accepted. - No revocation deletes provenance needed to explain past execution unless deletion policy explicitly requires it. - No interface projection may make hidden state indistinguishable from nonexistent state when the distinction is consequential. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/10-temporal-consistency-correction-and-forgetting.md (159 lines, 7.1 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Temporal Consistency and Correction Keeping intent, interpretation, execution, and memory synchronized over time Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **Human--computer relationships are distributed systems in miniature: intent can change while execution is in flight, observations can arrive late, interpretations can be stale, and multiple actors can update overlapping state.** # 1. Versioned interaction state t0 Intent v7 declared\ t1 Interpretation v7.1 proposed\ t2 Action based on v7.1 authorized\ t3 Human correction creates Intent v8\ t4 v7.1 action still executing\ t5 system must reconcile or stop; it may not pretend v7 remains current # 2. Consistency states -------------------------------------------------------------------------- **State** **Definition** **Expected behavior** ----------------------- -------------------------- ----------------------- Current Interpretation/execution Proceed. references latest governing relationship version. Stale-but-safe Older version in use, but Disclose and converge. protected invariants remain satisfied. Conflicted Two authorized updates Freeze consequential cannot both govern. action; surface conflict. Superseded New state explicitly Old state becomes replaces earlier state. historical-only. Revoked Authority or permission Prevent new actions; withdrawn. stop/rollback where contract requires. Unknown consistency System cannot prove which Stop at protected state governs. boundary. -------------------------------------------------------------------------- # 3. Correction economics Correctability is not sufficient if correction consumes more human effort than the automation saves. HCML therefore treats repair burden as a first-class evaluation dimension. ----------------------------------------------------------------------- **Metric** **Question** ----------------------------------- ----------------------------------- TTDM Time to Detect Misalignment: how long before the person or system notices the interpretation diverged? TTCI Time to Correct Interpretation: how long to establish the corrected shared state? Repair Turns How many interaction cycles are required? Correction Persistence Does the correction survive later context changes and sessions where it should? Repeated Misinterpretation Rate How often does a previously corrected mismatch recur? Supervision Load How much ongoing human attention is required to keep the system within bounds? ----------------------------------------------------------------------- # 4. Lifecycle and forgetting - Every durable state should define retention, expiry, supersession and deletion semantics. - Preferences should not become permanent merely because they were once useful. - Revoked authority must propagate to future action planning. - Historical evidence may need retention even when operational authority expires; privacy policy determines when deletion overrides auditability. - Ephemeral exploration should remain possible without automatic conversion into project memory. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/11-plural-actors-delegation-and-opacity.md (155 lines, 7.1 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Plural Actors, Delegation, and the Right to Opacity Authority when more than one human or computational actor shares the relationship Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The dyad "human ↔ computer" is a useful teaching diagram but an inadequate operating model. Real systems include multiple humans, services, models, policies, maintainers, institutions, and affected non-users.** # 1. Participant topology Humans: operator / author / maintainer / approver / regulator / affected non-user\ Computational actors: LLM / compiler / policy engine / database / runtime / sensor / evaluator\ \ Relationship State does not merge them.\ It records actor-relative claims, authority, evidence and consequence. # 2. Delegation graph ------------------------------------------------------------------------ **Capability** **Example authority** **Default risk posture** ----------------------- ------------------------ ----------------------- Inspect Read Low source/evidence/state. Propose Create candidate Low interpretation/action. Simulate Evaluate a hypothetical Low--medium world without mutation. Draft Modify non-authoritative Medium artifact. Execute reversible Perform action with Medium defined rollback. Execute irreversible Commit external High consequence. Accept Promote candidate to High governing state. Delegate Grant authority to Very high another actor. Revoke Withdraw prior Very high authority. ------------------------------------------------------------------------ # 3. Affected but absent participants A system may be mutually legible with its active operator and still fail people who are affected by its actions but are not present in the interaction. HCML therefore distinguishes represented stakeholders from affected stakeholders and requires explicit policy for whose interests and rights must constrain the relationship state. # 4. Right to opacity +-----------------------------------------------------------------------+ | **Mutual legibility is not compulsory legibility** | | | | Not every human thought, preference, hesitation, contradiction, or | | exploratory statement should become durable structured state. Human | | participants require room for privacy, ambiguity, tentative thought, | | revision, and non-persistence. | +=======================================================================+ +-----------------------------------------------------------------------+ ----------------------------------------------------------------------- **Human-state status** **Persistence** **Authority** ----------------------- ----------------------- ----------------------- Ephemeral Discard after None unless explicitly interaction/window. promoted. Tentative May be retained Does not govern temporarily with consequential action. visible uncertainty. Private Not exposed beyond Cannot be repurposed by declared audience. other actors. Declared Durable statement with Scope-dependent. provenance. Committed Frozen governing state. Authoritative within declared scope. ----------------------------------------------------------------------- # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/12-typed-uncertainty-and-disagreement.md (134 lines, 5.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Typed Uncertainty and Inspectable Disagreement Preventing confidence, evidence, interpretation, and consensus from collapsing into one score Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **A shared relationship model becomes dangerous if it converts all uncertainty into a single confidence number or treats disagreement as noise to be averaged away.** # 1. Uncertainty taxonomy ----------------------------------------------------------------------- **Type** **Example** **What it does not mean** ----------------------- ----------------------- ----------------------- Predictive probability Model estimates event Source is 70% reliable. likelihood at 0.7. Epistemic uncertainty Model lacks sufficient Outcome is random. information. Measurement precision Sensor/OCR estimate has Interpretation is bounded error. correct. Source reliability Evidence source has Claim is false. known limitations. Consensus dependence Multiple models share Independent sources/training confirmation. assumptions. Interpretation System confidence in Human endorsed the confidence mapping utterance to interpretation. intent. Human confidence Person reports Decision is accurate. confidence in a decision. Policy certainty Rule deterministically Rule is normatively applies. correct. ----------------------------------------------------------------------- # 2. Disagreement as state Human intent representation A\ System interpretation B\ Policy requirement C\ Observed world state D\ \ Do not collapse -\> one synthetic answer.\ Retain -\> A, B, C, D + their relationships + unresolved conflicts. # 3. Minimum uncertainty record UncertaintyRecord {\ subject\ uncertainty_type\ source\ method\ value_or_class\ calibration_status\ scope\ valid_at\ provenance\ } # 4. Projection rule Interfaces should project only the uncertainty needed for the current task while preserving access to provenance and deeper state. The objective is legibility bandwidth, not maximal information density. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/13-relationship-state-threat-model.md (155 lines, 6.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship-State Threat Model Security, manipulation, provenance, and authority attacks against the shared model Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **If relationship state becomes the place where intent, evidence, authority and acceptance are coordinated, then compromising that state can be more damaging than modifying an ordinary interface or chat transcript.** # 1. Threat classes ---------------------------------------------------------------------------- **Threat** **Example** **Required defense** ----------------------- ----------------------- ---------------------------- Intent forgery System records inferred Typed provenance + promotion preference as gate. user-declared. Authority escalation Adapter converts "can Capability/authority propose" into "can separation; deny by default. execute." Evidence laundering AI-produced claim Source class + immutable appears as external lineage. observation. Confidence laundering Constant or Typed uncertainty; allow uncalibrated score absence. presented as measured confidence. History rewriting Prior decision changed Append-only/tamper-evident after outcome. history. Conflict erasure Disagreeing sources Preserve contradictory merged into one value. records. Projection deception UI hides Loss-aware projection unavailable/blocked contract. state so it appears nonexistent. Stale-intent execution Action continues after Version binding + revocation governing intent propagation. changed. Cross-context leakage Preference from one Scope-bound memory and relationship reused in authority. another. Model-side prompt Untrusted content Tool/result isolation; fixed injection modifies governing schemas; explicit authority state. path. Stakeholder omission Operator-only model Stakeholder/rights ignores affected constraints in policy layer. non-user. ---------------------------------------------------------------------------- # 2. Security invariants - Every state mutation names actor, authority, scope, prior version and resulting version. - Adapters may reduce authority but may not expand it. - Promotion and execution are distinct operations. - Disagreement is data and must not be normalized away without a named rule. - Lossy projections disclose what they omit or transform. - Sensitive human state has explicit retention and audience policy. - Unknown or unverifiable provenance blocks protected promotion. # 3. Audit object RelationshipEvent {\ event_id\ relationship_id\ actor_id\ action\ authority_ref\ input_refs\[\]\ previous_version\ resulting_version\ evidence_refs\[\]\ timestamp_or_order\ integrity_digest\ } # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/14-measurement-and-empirical-validation-program.md (187 lines, 8.8 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** HCML Measurement and Empirical Validation Program How to determine whether mutual legibility actually helps people Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The research should fail cleanly if explicit relationship state adds complexity without improving prediction, correction, calibration, agency, coordination, recovery, or task outcomes.** # 1. Primary constructs ----------------------------------------------------------------------- **Construct** **Operational **Candidate measure** question** ----------------------- ----------------------- ----------------------- Behavioral Can the human predict Prediction accuracy / predictability what the system will do calibration. next? Interpretation accuracy Does the system Human-confirmed correctly characterize classification explicitly declared accuracy. intent? Correction efficiency Can mismatches be TTDM, TTCI, repair repaired quickly and turns, recurrence. persistently? Trust calibration Does reliance track Calibration error, actual system over-/under-reliance. competence? Agency legibility Can the person identify Authority what they can stop, identification override, revoke or accuracy + action delegate? success. Provenance Can users distinguish Source-class comprehension observation, inference, identification. policy and recommendation? Coordination Do human and system Task success, errors, complete joint tasks handoff failures. more reliably? Recovery Can the relationship Time-to-recovery, recover after a system retained context, error? repeated-error rate. Legibility burden How much Time, interruptions, cognitive/supervisory workload, abandonment. cost does the added structure create? Plural fairness Are affected Constraint coverage / stakeholder constraints violation rate; represented and domain-specific human respected? review. ----------------------------------------------------------------------- # 2. Core experiment families ----------------------------------------------------------------------- **Study** **Comparison** **Falsification signal** ----------------------- ----------------------- ----------------------- Intent interpretation Natural-language-only No reduction in vs explicit misunderstanding or intent/constraint repair cost. state. Authority comprehension Conventional Users remain unable to permissions vs visible predict/override system delegation graph. actions. Provenance Flat answer vs typed No calibration gain or evidence/provenance increased over-trust. view. Temporal correction Chat-history context vs No reduction in versioned relationship stale-intent execution state. or repeated corrections. Disagreement Merged answer vs Conflict view harms inspectable conflict decisions without state. measurable compensating benefit. Legibility bandwidth Full state dump vs Projection either hides task-relative consequential state or projection. offers no workload benefit. Longitudinal memory Persistent state vs Scoped model does not scoped reduce stale lifecycle/forgetting. preference/authority errors. ----------------------------------------------------------------------- # 3. Claim ladder Representable != Implemented != Tested != Human-observed != Empirically validated != Generalizable A system can successfully implement relationship-state semantics while the human-facing theory fails. That is a valid research result and should narrow the theory rather than be reframed as success. # 4. Stop conditions - Added relationship-state complexity materially increases task time or error without compensating benefit. - Users cannot correctly interpret provenance/authority despite interface refinement. - Correction cost remains equal to or worse than conventional interaction. - The model requires inferential access to human state that cannot be ethically or reliably measured. - Simpler interface or workflow mechanisms produce equivalent outcomes with lower complexity. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/15-relationship-state-research-roadmap.md (154 lines, 7.2 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship State Research Roadmap A bounded path from implemented mechanisms to a falsifiable HCML theory Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The next step should not be another universal abstraction. It should be a sequence of narrow experiments that force the relationship-state model against cases capable of breaking it.** # 1. Workstreams ------------------------------------------------------------------------------- **Phase** **Deliverable** **Promotion gate** ----------------------- ----------------------- ------------------------------- R0 Canonical Can encode existing project RelationshipState examples without invented schema and vocabulary. facts. R1 Conversation Inference never self-promotes; intent/provenance corrections are versioned. adapter. R2 Delegation graph + Capability and authority remain protected-action separable in tests. evaluator. R3 Typed uncertainty + Conflicting evidence survives disagreement ledger. projection and round-trip. R4 Temporal consistency Stale/revoked intent blocks engine. protected execution. R5 Relationship event Historical explanation and log + scoped deletion both work. lifecycle/forgetting. R6 Threat-model red-team Forgery/escalation/laundering corpus. tests fail closed. R7 Two controlled human At least one measurable HCML studies. benefit or principled narrowing. R8 Longitudinal Correction persistence and correction/memory stale-state cost measured. study. R9 Cross-domain Same relation primitives replication. survive at least two materially different domains. R10 Theory promotion Promote, narrow, rename, or decision. reject based on retained evidence. ------------------------------------------------------------------------------- # 2. First prototype +-----------------------------------------------------------------------+ | **Recommended next experiment** | | | | Build a small relationship-state layer over one existing | | conversational/agent workflow. Capture only intent representation, | | interpretation, authority, evidence, uncertainty, correction, version | | and execution reference. Compare it against the same workflow using | | chat history alone. | +=======================================================================+ +-----------------------------------------------------------------------+ # 3. What not to build yet - No universal ontology of human meaning. - No cross-project global user model. - No automatic behavioral inference promoted as intent. - No scalar "mutual legibility score." - No assumption that more visible state is always better. - No autonomous promotion of machine interpretations. - No requirement that existing projects adopt the theory before empirical value is demonstrated. # 4. Decision rule Keep the concept only where explicit relationship state\ reduces consequential guessing between participants.\ \ If a simpler representation achieves the same result,\ use the simpler representation. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: HCML-Relationship-State-Extension/README.md (35 lines, 2.5 KiB) ======================================================================== # Human–Computer Mutual Legibility — Working Research Corpus This corpus formalizes a recurring concept observed across the supplied project implementations: systems become more trustworthy and capable when consequential human intent and machine state are made mutually legible through explicit representations of intent, evidence, authority, uncertainty, provenance, correction, and consequence. ## Documents - `00-program-charter.docx` — program definition, scope, non-goals, success ladder. - `01-theory-of-mutual-legibility.docx` — conceptual theory and human–machine relationship model. - `02-evidence-across-implementations.docx` — cross-project evidence and limitations. - `03-shared-computational-model-architecture.docx` — technical architecture and state model. - `04-mutual-interaction-authority-protocol.docx` — interaction, correction, authority, and negotiation protocol. - `05-research-validation-program.docx` — hypotheses, experiments, metrics, falsification, and claim boundaries. - `06-publication-framework.docx` — structure and claim discipline for the long-form article. - `07-design-principles-implementation-heuristics.docx` — reusable engineering principles and review checklist. ## Working term **Human–Computer Mutual Legibility (HCML)** is provisional. It does not imply mutual consciousness or equal agency. It denotes an engineered condition in which humans can inspect consequential machine state and machines receive explicit representations of consequential human intent, authority, constraints, correction, and acceptance. ## Evidence boundary The project corpora provide architectural evidence and implemented mechanisms. They do not yet empirically establish that HCML improves trust, understanding, safety, or performance for human users. Those claims are framed as hypotheses in the research program. ## Relationship State extension The second HCML document family refines the initial “shared model” thesis into an explicit **Relationship State** model and records the unresolved theory, security, temporal, plural-actor, uncertainty, privacy, and empirical-validation gaps. - `08-open-gaps-and-missing-theory.docx` - `09-relationship-state-model.docx` - `10-temporal-consistency-correction-and-forgetting.docx` - `11-plural-actors-delegation-and-opacity.docx` - `12-typed-uncertainty-and-disagreement.docx` - `13-relationship-state-threat-model.docx` - `14-measurement-and-empirical-validation-program.docx` - `15-relationship-state-research-roadmap.docx` ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/00-program-charter.md (174 lines, 7.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Mutual Legibility Program Charter A research program for shared human--computer models of intent, state, evidence, authority, and consequence Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **Working thesis: the next major human--computer interface may be a shared computational model that makes both human intent and machine state mutually inspectable, correctable, and governable.** # 1. Definition Human--Computer Mutual Legibility (HCML) is the working name for a condition in which a person can inspect what a computational system observed, inferred, believes to be relevant, changed, or is authorized to do, while the computational system receives explicit representations of human intent, constraints, authority, corrections, acceptance, and exit conditions. Mutual legibility does not imply shared consciousness, shared interpretation, or equal agency. It describes an engineered relationship in which consequential state is not forced to remain implicit on either side. +-----------------------------------------------------------------------+ | **Core proposition** | | | | Many failures attributed to "bad interfaces," "AI unreliability," or | | "poor context" are instances of one side having to infer | | consequential state that the other side could have represented | | explicitly. | +=======================================================================+ +-----------------------------------------------------------------------+ # 2. The historical inversion EARLY COMPUTING\ Human -\> instructions -\> Machine\ \ PERSONAL COMPUTING\ Human \<-\> interface / feedback \<-\> Machine\ \ AI COMPUTING\ Human \<-\> shared computational model \<-\> Machine\ intent / evidence / authority / uncertainty / state Classical HCI largely worked to make machines legible to people. AI systems create the reciprocal pressure: human intent, authority, uncertainty, and correction must become legible to machines without allowing the machine to silently convert its interpretation into human intent. # 3. Program questions - What state must be explicit for human and machine to coordinate without hidden inference? - Which parts of the shared model are machine-derived, human-authored, contract-relative, observed, or unresolved? - How can one side correct the other without collapsing authority boundaries? - When should machine outputs remain candidate state rather than operational truth? - How should confidence, uncertainty, provenance, disagreement, and absence travel with representations? - What representations preserve meaning, and which transformations must disclose loss? - How can histories, diffs, replay, and counterfactuals make the relationship inspectable over time? - Which benefits are mechanical and which require empirical human-subject validation? # 4. Non-goals - HCML is not a claim that computers understand people in the human sense. - It is not a universal ontology of human intention or meaning. - It does not make every decision collaborative; some systems should remain tools under unilateral human authority. - It does not treat visibility as authority, prediction as fact, confidence as correctness, or execution as success. - It does not assume more AI autonomy is desirable. In several supplied systems the explicit design goal is to limit or route autonomy. # 5. Success ladder ----------------------------------------------------------------------- **Level** **Result** **Independent value** ----------------------- ----------------------- ----------------------- L1 Machine state and Debugging, calibration, provenance become traceability inspectable L2 Human intent and Less accidental authority become delegation and hidden explicit inputs inference L3 Differences between Correction and human and machine disagreement become models become visible structured L4 Shared state can be Safer AI-assisted negotiated through workflows and authoring bounded operations L5 The shared model Continuity across UI, persists across AI, tools, and representations and execution runtime changes ----------------------------------------------------------------------- # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/01-theory-of-mutual-legibility.md (178 lines, 7.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Theory of Human--Computer Mutual Legibility A conceptual model of reciprocal legibility without anthropomorphism Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **The central object is not the interface. It is the relationship between two partial models of the same consequential situation.** # 1. Three models, not one HCML distinguishes the human model, the machine model, and the shared computational model. The shared model is not presumed to contain everything either side knows or experiences. It contains the subset made explicit enough to coordinate action, evidence, authority, and correction. Human Model H\ goals, values, interpretation, stakes, preferences, tacit context\ \ Machine Model M\ observed inputs, derived state, candidate conclusions, capabilities, predictions\ \ Shared Model S\ intent, declared constraints, identities, evidence, provenance, authority, uncertainty, operations, history # 2. Mutual legibility loop Human intent / correction\ \|\ v\ Shared Model S \<\-\-\-- Machine observations / derivations\ \| \^\ v \|\ Human-visible projection machine-readable contract\ \| \|\ +\-\-\-\-\-- action / feedback + The loop becomes useful when discrepancies are representable. The system need not pretend that H = M = S. In fact, disagreement is often the most informative state. # 3. Core distinctions ----------------------------------------------------------------------- **Distinction** **Why it must remain separate** ----------------------------------- ----------------------------------- Intent vs. instruction A command may be syntactically valid while failing the purpose that motivated it. Observation vs. interpretation A system can record an event without establishing what it means to a person. Capability vs. authority A system may technically be able to act without being permitted to act. Confidence vs. correctness Confidence is evidence about the model or process, not truth. Candidate vs. accepted state Machine output can enter a shared model without becoming operational authority. Execution vs. success An operation can run and still fail the intended outcome. Representation vs. underlying state A UI can hide, transform, or introduce structure. Agreement vs. independent evidence Multiple systems can converge because they share sources or assumptions. Record vs. evidence A trace becomes evidence only under declared interpretation and provenance rules. Formalization vs. certainty Formal structure relocates ambiguity into inspectable assumptions; it does not erase ambiguity. ----------------------------------------------------------------------- # 4. Negotiation without anthropomorphism Negotiation here means bounded model revision, not human-like bargaining. Either side can introduce new state that causes the shared model to change, but the type of change and its authority are explicit. A human can revise a preference or grant authority. A machine can introduce evidence, identify a contradiction, or propose an alternative. Neither operation should be mistaken for the other. Human: "I want X, but Y is non-negotiable."\ Machine: proposes A and B with evidence.\ Shared state: Y blocks A; B remains candidate.\ Human: accepts B.\ System: records authority + executes B.\ Evidence: outcome returns to the shared state. # 5. A stronger definition of interface Under HCML, an interface is one projection of a shared interaction state rather than the location where the interaction "is." A graphical UI, command line, AI conversation, scene editor, accessibility representation, runtime diagnostic, and machine-readable API can all expose different projections of the same underlying state, provided their transformations and losses are known. # 6. Human asymmetries that remain - Humans retain lived experience, value judgment, meaning attribution, and stakes that are not reducible to machine state. - Machine systems can preserve and compute state at scales humans cannot directly inspect. - Authority can be asymmetric by design. A human-owned system may permit machine proposals while reserving promotion or execution. - Legibility is therefore reciprocal but not necessarily symmetric. # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/02-evidence-across-implementations.md (208 lines, 10.0 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Evidence Across Implementations How seven independent project families converge on the same relationship pattern Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **The case for HCML is currently architectural and comparative: different projects repeatedly solve different problems by making hidden relationships explicit.** # 1. Cross-project convergence ---------------------------------------------------------------------------- **Project** **Problem **Mechanism** **HCML encountered** implication** ----------------- ----------------- ---------------------- ----------------- Fundamental Representation Renderer-agnostic Machine state can was becoming field, governed remain confused with the projections, independent of underlying query/snapshot/diff, any one computational provenance-aware human-facing world. diagnostics. representation. FCI Formal models Explicit separation of The shared model risked state, semantics, must disclose its overclaiming projection, epistemic human meaning and interpretation, boundary. behavior. opportunity, measurement, evidence. Scene-Builder UI, CLI, AI, One serializable scene Humans and undo, and document and one machine actors collaboration generic command bus. can share the could become same operational separate mutation language without paths. sharing authority. Re-Mesh Downstream tools Recipes, confidence, Inference should could not know "why", overruled travel with its how generated classification, evidence and assets were quality metrics, history. repaired or provenance. inferred. Comic OCR Multiple Candidate state, Machine claims recognition per-engine provenance, should remain engines can no self-promotion, qualified rather disagree; omit false confidence. than becoming fabricated truth by confidence can ingestion. contaminate later decisions. PDP AI panels can Frozen human weights, The machine can defer to operator human gates, read-only argue; the human pressure or execution integration, retains silently move append-only audit. consequential decision decision criteria. ownership. IEPE Agents can Intent chain, bounded Conversation rewrite criteria, authority, independent becomes input self-approve, evaluation, promotion evidence; repeat failed gates, durable authority and work, or lose evidence and negative promotion are project intent. results. separately represented. ---------------------------------------------------------------------------- # 2. Recurring pattern Implicit relationship\ -\> explicit relationship\ -\> provenance-bearing relationship\ -\> inspectable relationship\ -\> correctable relationship\ -\> authority-bounded action # 3. What these implementations already demonstrate - One canonical operational representation can be shared across human and machine actors without granting them identical permissions. - Provenance, uncertainty, confidence, and diagnostic state can travel with machine-derived outputs. - A system can preserve machine output as candidate evidence rather than automatically promoting it. - Human decision variables and execution gates can be structurally protected from model self-revision. - Runtime state can remain inspectable through snapshots, diffs, replay, and normalized evidence logs. - Generated or projected representations can be prevented from silently changing the authority-bearing source. # 4. What these implementations do not yet demonstrate - That a shared model improves human understanding across broad populations. - That explicit mutual legibility reduces over-trust, under-trust, or automation bias in general. - That one ontology can represent human intent across domains without destructive simplification. - That users prefer the additional transparency or can use it without excessive cognitive load. - That machine-readable human intent is faithful to tacit or changing human intent. - That greater mutual legibility always produces better outcomes; it may expose complexity without helping action. # 5. Strongest evidence patterns to reuse ----------------------------------------------------------------------- **Pattern** **Why it is strong** ----------------------------------- ----------------------------------- Authority encoded in system PDP and IEPE make unauthorized structure transitions impossible or explicitly blocked rather than relying on prompt obedience. Refusal to fabricate missing OCR and Fundamental preserve certainty absence/unknown state instead of inventing confidence or a plausible visualization. Independent evaluation IEPE separates candidate authorship from promotion; PDP separates model analysis from human weight custody. Shared operation representation Scene-Builder's command bus lets UI, CLI, agent, and collaboration use the same mutation vocabulary. Loss-aware projection FCI/Fundamental require projection and comparison boundaries rather than assuming representations are equivalent. Durable history PDP event chains, IEPE evidence ledgers, Fundamental snapshots/replay, and Re-Mesh recipes preserve how current state came to exist. ----------------------------------------------------------------------- # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/03-shared-computational-model-architecture.md (230 lines, 9.2 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Shared Computational Model Architecture A technical substrate for intent, evidence, authority, provenance, correction, and consequence Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **HCML requires a shared model that is explicit enough for machines to compute over and bounded enough that it does not pretend to contain the whole human situation.** # 1. Canonical state families ----------------------------------------------------------------------- **State family** **Examples** **Primary authority** ----------------------- ----------------------- ----------------------- Intent desired outcome, Human / authorized protected qualities, organization exclusions, preferences World / domain state objects, facts, Authoritative system or observed environment, sensor/source current runtime state Evidence sources, model outputs, Source-specific; never measurements, traces, collapsed without contradictions provenance Interpretation meaning assignments, Human, model, or classifications, contract --- explicitly hypotheses typed Authority permissions, promotion Human / governance rights, execution contract gates, scope Uncertainty confidence, unknowns, Producer + evaluator missing evidence, disagreement Operations available actions, System contract preconditions, side effects History snapshots, diffs, Append-only evidence decisions, rejected substrate alternatives, replay Projection UI, CLI, agent context, Projection contract; visualization, downstream of canonical accessible fallback state ----------------------------------------------------------------------- # 2. Minimal shared-state schema SharedInteractionState {\ intent\[\]\ entities\[\]\ relationships\[\]\ evidence\[\]\ interpretations\[\]\ uncertainty\[\]\ authority\[\]\ operations\[\]\ decisions\[\]\ projections\[\]\ history\[\]\ }\ \ Every consequential record carries:\ identity + source + provenance + status + authority + timestamps/version # 3. State maturity ----------------------------------------------------------------------- **Status** **Meaning** ----------------------------------- ----------------------------------- Observed Something was recorded; no interpretation implied. Candidate A machine or human has proposed a state or conclusion. Qualified The candidate passed a declared evaluation contract. Accepted An authorized actor adopted it for the current scope. Operational It is permitted to drive execution. Verified A required mechanical/empirical check established the specified property. Rejected It remains in history but must not drive current state. Unknown The system cannot establish the proposition from available evidence. ----------------------------------------------------------------------- # 4. Authority model Authority should attach to actions and promotions, not merely identities. A system can be capable of producing a recommendation while lacking authority to change weights, promote candidate facts, spend money, mutate protected data, or accept its own work. Capability != Permission != Promotion Authority\ \ AI can propose(candidate)\ AI can supply(evidence)\ AI can evaluate(candidate) \# if independent evaluator role permits\ AI cannot promote(candidate) \# unless explicit low-risk policy grants it\ Human can accept(candidate)\ System can execute(accepted) \# only if action authority is granted # 5. Difference and correction Mutual legibility becomes useful when the shared model can represent disagreement instead of forcing one value. Corrections should preserve what changed, who changed it, why, and what evidence justified the change. Human intent H1 != Machine interpretation M1\ -\> discrepancy record\ -\> explanation / evidence\ -\> bounded revision\ -\> H2 or M2 or unresolved\ -\> retained history # 6. Projection contract - Every projection declares what source state it reads. - Lossy or interpretive transformations are disclosed. - Unavailable is not rendered as absent. - Disagreement is not flattened into a single value without a declared resolution rule. - Confidence and provenance are not removed when they are required for downstream trust decisions. - Generated context is downstream; it does not silently rewrite canonical state. # 7. Interchange with existing systems ----------------------------------------------------------------------- **System** **Adapter role** ----------------------------------- ----------------------------------- Fundamental Runtime/world-state and projection adapter Scene-Builder Authoring operation and document-state adapter Re-Mesh Asset inference/provenance adapter Comic OCR Candidate evidence adapter PDP Decision ownership / human gate adapter IEPE Intent, work authority, qualification, and promotion adapter RRSA / compiler semantics Machine semantic-state adapter for software itself ----------------------------------------------------------------------- # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/04-mutual-interaction-authority-protocol.md (196 lines, 8.1 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Mutual Interaction and Authority Protocol How humans and computational systems exchange intent, evidence, correction, and control Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **The goal is not frictionless automation. The goal is to make consequential delegation, disagreement, correction, and acceptance explicit enough to inspect.** # 1. Interaction phases 1. Intent declaration --- capture desired outcome, constraints, protected qualities, exclusions, and uncertainty. 2. Machine interpretation --- system states what it believes the task, state, and decision variables are. 3. Alignment check --- mismatches, missing context, and unresolvable ambiguity remain visible. 4. Candidate formation --- machine or human proposes operations or conclusions without automatic promotion. 5. Evidence attachment --- each proposal carries provenance, confidence/uncertainty, assumptions, and alternatives where material. 6. Authority gate --- an authorized actor or policy determines what may become operational. 7. Execution --- the system acts only within granted scope. 8. Observation --- actual outcome, errors, and side effects return as new evidence. 9. Reconciliation --- shared state is updated without erasing prior states or negative results. 10. Exit / revoke --- the human or governing authority can terminate or reduce delegated authority. # 2. Human role - Own consequential goals, values, stakes, and protected constraints. - Correct machine interpretations of intent. - Grant, deny, narrow, or revoke authority. - Accept responsibility for decisions reserved to human judgment. - Retain the ability to exit the interaction where system design permits. # 3. Machine role - Make its current interpretation inspectable. - Preserve uncertainty instead of filling gaps with fabricated certainty. - Expose evidence and provenance supporting conclusions. - Distinguish inability, lack of permission, lack of evidence, and rejection. - Propose alternatives and consequences without laundering recommendations into authority. - Record what it changed and why. # 4. Correction classes ----------------------------------------------------------------------- **Correction** **Example** **Required behavior** ----------------------- ----------------------- ----------------------- Intent correction "I meant preserve Update intent state; do layout, not not rewrite prior appearance." evidence. Factual correction A source or sensor Attach new evidence; invalidates a machine recompute affected assumption. candidates. Authority correction Human withdraws Stop protected action; permission to publish record revocation. or execute. Preference revision Human changes a Create new decision non-protected priority. state with provenance. Model self-correction System discovers an Mark prior candidate error in its own superseded/rejected; inference. preserve history. Unresolved disagreement Human and system cannot Retain disagreement; do establish a shared not force consensus. conclusion. ----------------------------------------------------------------------- # 5. Anti-patterns ----------------------------------------------------------------------- **Anti-pattern** **Failure** ----------------------------------- ----------------------------------- Inference as authority System guesses intent and acts as if explicitly authorized. Conversation as commitment A casual utterance silently becomes a durable project or financial decision. Confidence laundering A guessed or constant confidence value is stored as measured certainty. Self-promotion The same agent generates, evaluates, and approves its own work without an independent gate. Representation collapse A hidden or unavailable operation is rendered as nonexistent. Disagreement erasure Multiple provenance records are merged into one "consensus" value. Speech as world event A model's new opinion is treated as if the external world changed. Silent repair Automation overwrites a human-modified value while "backfilling" missing metadata. ----------------------------------------------------------------------- # 6. Negotiability test An interaction is meaningfully negotiable when both human correction and machine evidence can change the shared model through explicit, typed operations, while neither side can silently assume the other side's authority. This is a stronger condition than conversational naturalness. # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/05-research-validation-program.md (213 lines, 9.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Research and Validation Program Falsifiable questions, measurements, experiments, and limits for Human--Computer Mutual Legibility Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **The broad theory should be treated as a research program. The supplied systems establish mechanisms; human benefit remains an empirical question.** # 1. Hypotheses ----------------------------------------------------------------------- **ID** **Hypothesis** **Primary falsification** ----------------------- ----------------------- ----------------------- H1 Explicit machine state No improvement in and provenance improve diagnosis accuracy/time users' ability to versus conventional UI. identify why a system acted. H2 Explicit human intent No reduction in and authority reduce authority errors or accidental delegation users become less able and unauthorized to identify action. responsibility. H3 Candidate/accepted Users over-trust separation improves candidate output calibration of trust in equally or more than machine output. baseline. H4 Visible disagreement Discrimination or and uncertainty improve calibration worsens. discrimination between supported and unsupported conclusions. H5 Shared operation Equivalent tasks representations improve diverge materially by cross-modal continuity interface or produce among UI, CLI, AI, and inconsistent state. collaborators. H6 History, diff, and Recovery time or error replay improve recovery rate does not improve. from human--machine misunderstandings. H7 Authority-bounded agent Projects drift equally systems preserve intent despite explicit better over authority/evidence long-running work. chains. ----------------------------------------------------------------------- # 2. Measurement families ----------------------------------------------------------------------- **Construct** **Operational measures** ----------------------------------- ----------------------------------- Mutual legibility Accuracy of human model of machine state + accuracy of machine representation of declared human intent. Calibration Confidence/reliance aligned with measured system reliability; over-trust and under-trust tracked separately. Correction cost Time/steps required to identify and repair a human--machine model mismatch. Authority clarity Ability to identify who may decide, approve, execute, and revoke a consequential action. Provenance retention Fraction of consequential outputs that preserve source, derivation, uncertainty, and revision history. Projection fidelity Which declared semantic relations survive modality/UI degradation. Continuity Ability to move between UI, CLI, AI, and runtime representations without state divergence. Cognitive load Time, errors, subjective workload, and comprehension cost introduced by added explicitness. ----------------------------------------------------------------------- # 3. Core experiments 1. Diagnostic explanation study: conventional interface versus provenance-bearing state explanation. 2. Authority study: prompt-only agent controls versus structural permission and promotion gates. 3. Trust calibration study: plain AI answer versus candidate/accepted status plus provenance and uncertainty. 4. Mutual correction study: measure recovery when human and machine models intentionally diverge. 5. Projection degradation study: remove motion, color, canvas, or visual hierarchy and test whether meaning survives alternate carriers. 6. Cross-interface continuity study: perform the same task through UI, CLI, and AI using one command/state representation. 7. Longitudinal agent project study: compare project drift and rework with and without intent/evidence/promotion memory. # 4. Claim taxonomy Documented != Implemented != Tested != Empirically Validated\ \ Mechanically established != Contract-relative != Human-interpreted != Empirically measured A central protection is to keep implementation success separate from claims about human comprehension, trust, intent fidelity, usefulness, delight, or behavior. Those require actual participants and declared measurement contracts. # 5. Negative results worth preserving - Users ignore provenance and authority metadata under realistic time pressure. - Explicit shared state creates excessive cognitive load. - Natural conversation communicates intent as well as structured intent in low-stakes tasks. - Different domains require incompatible intent representations. - Machine explanations increase perceived confidence without increasing discrimination. - Human correction introduces more inconsistency than it resolves. - Shared command models help tooling consistency but do not improve human understanding. # 6. Scientific boundary The research should seek bounded explanation, not a universal model of human--computer relationships. Formalization makes assumptions and uncertainty inspectable. It does not establish that those assumptions capture lived meaning, culture, trust, cognition, or social power. # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/06-publication-framework.md (187 lines, 7.8 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Publication Framework From interface to mutual legibility: a long-form article and research-paper structure Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **The publishable story is not "I built several systems." It is that unrelated systems repeatedly forced the same correction to the conventional human--computer model.** # 1. Proposed article thesis +-----------------------------------------------------------------------+ | **Primary thesis** | | | | The next interface may be a shared computational model through which | | humans and machines make consequential state mutually legible: humans | | expose intent, authority, constraints, and correction; machines | | expose state, evidence, inference, uncertainty, and consequence. | +=======================================================================+ +-----------------------------------------------------------------------+ # 2. Narrative sequence 1. Open with the historical asymmetry: people learned to express instructions machines could execute; HCI then made machines progressively legible to people. 2. Introduce the AI inversion: machines now require richer representations of human intent, authority, context, and correction. 3. Show Fundamental: representation is only a projection; the underlying world must remain inspectable. 4. Show FCI: explicit semantics do not justify claims about human interpretation; boundaries and uncertainty must remain visible. 5. Show Scene-Builder: UI, CLI, AI, undo, and collaboration become peers when they share one command representation. 6. Show Re-Mesh and OCR: machine inference becomes safer when confidence, provenance, candidate status, and history travel with the result. 7. Show PDP: argument and evidence can belong to machines while weights, stakes, and exit remain human. 8. Show IEPE: intent, bounded authority, independent evaluation, and promotion allow agentic work without letting the agent become the project's authority. 9. Synthesize: the recurring move is from implicit relationship to explicit, inspectable, negotiable relationship. 10. End with the research question: what happens if mutual legibility becomes a first-class substrate rather than a UI feature? # 3. Terms to introduce carefully ----------------------------------------------------------------------- **Term** **Definition / warning** ----------------------------------- ----------------------------------- Mutual legibility Reciprocal inspectability of consequential human and machine state; not mutual consciousness. Shared computational model The explicit coordination state; not a complete representation of either party. Negotiability Ability to revise shared state through bounded, provenance-bearing operations. Epistemic provenance Who/what established a claim and under what evidence/derivation. Authority provenance Who/what may promote, accept, execute, or revoke a state. Projection A representation of underlying state that may preserve, transform, omit, or introduce structure. Candidate state Machine/human proposal that has not yet been granted operational authority. ----------------------------------------------------------------------- # 4. Claims the article can make now - The supplied implementations repeatedly encode intent, evidence, authority, provenance, candidate status, projections, snapshots, or common operations as first-class state. - These mechanisms reduce the amount of consequential information that downstream systems must infer implicitly. - Several projects structurally prevent machine or downstream representations from silently acquiring authority they were not granted. - The convergence is sufficient to motivate a broader research hypothesis. # 5. Claims that must remain hypotheses - That mutual legibility is a new general paradigm of HCI. - That it improves trust, understanding, productivity, safety, or decision quality for most users. - That the proposed state model generalizes across cultures, institutions, and high-stakes domains. - That explicit state is always preferable to implicit interaction or direct manipulation. # 6. Candidate titles - The Interface Is Becoming a Shared Model - Beyond the Interface: Making Humans and Computers Mutually Legible - The Missing Relationship Layer in Software - When the Machine Must Understand What We Mean - From Human--Computer Interaction to Human--Computer Mutual Legibility - Make the Relationship Explicit # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/07-design-principles-implementation-heuristics.md (193 lines, 8.3 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Design Principles and Implementation Heuristics A reusable checklist for systems that aim to support mutual legibility Working research specification · August 2026 **Working status** This document records a research synthesis grounded in the supplied project corpora. It distinguishes implemented mechanisms from broader human--computer interaction hypotheses. It does not claim that the proposed theory is empirically validated. **These principles translate the theory into engineering constraints that can be applied independently of any one project or technology stack.** # 1. Canonical principles -------------------------------------------------------------------------- **Principle** **Engineering consequence** ----------------------------------- -------------------------------------- Represent intent, do not infer it Allow systems to propose an indefinitely interpretation of intent, but make consequential assumptions inspectable and correctable. Capability is not authority A callable tool, API, or model ability does not imply permission to use it. Machine output enters as qualified Use state candidate/accepted/verified/rejected states where downstream consequences matter. Confidence must be earned and Unknown confidence is better than sourced fabricated confidence. Preserve disagreement Do not merge conflicting provenance into one value merely for display simplicity. Projection is downstream UI and generated context should not silently rewrite canonical state. Make loss visible If a representation omits uncertainty, relationships, causality, or alternatives, disclose that transformation. One operation, many actors Where useful, UI, CLI, AI, automation, and collaborators should share the same typed operation vocabulary. History is part of the state Preserve snapshots, diffs, rejected alternatives, evidence, and authority changes. Evaluation is not promotion A system can assess an artifact without gaining the authority to approve it. Refuse unsupported views When evidence is insufficient, show that insufficiency instead of producing a plausible visualization. Optimize for correction A good shared model makes a mistaken interpretation cheap to identify, explain, and repair. -------------------------------------------------------------------------- # 2. Minimum viable HCML layer - Stable identities for people/agents, artifacts, claims, actions, and decisions. - Explicit intent/constraints record. - Authority and permission record. - Provenance on machine-derived consequential state. - Unknown/candidate/accepted/rejected status. - One canonical mutation path or clearly reconciled paths. - Append-only or reviewable history. - Projection rules that distinguish hidden from nonexistent. - Correction and revocation operations. - Diagnostics exposing why a consequential state exists. # 3. Maturity ladder for implementations ----------------------------------------------------------------------- **Stage** **Description** ----------------------------------- ----------------------------------- M0 Implicit interaction: human and machine infer most consequential state from inputs/outputs. M1 Inspectable machine state: provenance/diagnostics available. M2 Explicit human intent and authority represented. M3 Candidate/accepted states and correction workflows. M4 Shared commands and cross-interface continuity. M5 Persistent shared model with diffs, replay, counterfactuals, and governed projections. M6 Empirically validated mutual-legibility benefits for a declared population/task/domain. ----------------------------------------------------------------------- # 4. Review questions - What consequential fact is currently implicit? - Who is expected to infer it? - Could it be represented without pretending to know more than we do? - Who has authority to create, change, accept, or execute it? - What happens when human and machine interpretations disagree? - Can the system represent "unknown," "not permitted," "not observed," and "rejected" separately? - Does confidence/provenance survive the representation boundary? - Can a user reconstruct why the current state exists? - Can the system be corrected without destroying history? - What human benefit is actually measured rather than assumed? # Source basis and claim boundary The synthesis below is grounded in the supplied project corpora. The projects do not themselves establish a general theory of human--computer mutual legibility; they provide implemented mechanisms and research doctrines from which the broader hypothesis is inferred. ----------------------------------------------------------------------- **Project / corpus** **Relevant contribution** ----------------------------------- ----------------------------------- Fundamental Engine v0.10.0 Renderer-independent runtime; reciprocal host/field state; query, snapshot, diff, provenance and loss-aware diagnostics. FCI v0.5.0 Separates state, semantics, projection, interpretation, opportunity, measurement and evidence; formalization exposes uncertainty. Scene-Builder v0.1.0 One scene document and command bus shared by UI, CLI, AI and collaborators; pure decisions separated from rendering. Re-Mesh v0.1.0 Assets retain recipe, confidence, provenance, affordances and quality diagnostics. Manga & Comic OCR Rust Multiple engines retain candidate outputs/provenance; machine output does not self-promote; false confidence is omitted. PDP v1.3.0 Systems supply evidence/argument; humans retain weights, stakes and exit through structural gates. IEPE v0.2.0 Intent, bounded authority, independent evaluation, promotion gates and durable negative evidence. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/08-open-gaps-and-missing-theory.md (177 lines, 8.2 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Open Gaps and Missing Theory What remains unresolved after the first HCML formulation Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The largest unresolved problem is not representation. It is deciding what may legitimately become relationship state, who may establish it, how long it remains valid, and how disagreement survives without being silently resolved.** # 1. Gap map ----------------------------------------------------------------------- **Gap** **Why it matters** **Failure if ignored** ----------------------- ----------------------- ----------------------- Represented intent A human utterance is System upgrades evidence about intent, interpretation into not intent itself. authority. Legibility vs agreement Understanding does not System treats require convergence. disagreement as failure to align. Distributed machine LLM, compiler, Machine prose is state database, policy engine mistaken for system and runtime may truth. disagree. Legibility bandwidth Complete transparency Technically inspectable can overwhelm. but practically unusable systems. Temporal consistency Intent, interpretation Agent faithfully and execution evolve at executes stale intent. different times. Correction economics Repair can become more Human becomes permanent burdensome than the supervisor. original work. Typed uncertainty Confidence is not one Probabilities, source thing. quality and human confidence collapse into one number. Delegation topology Authority varies by Permissions become too action, risk, coarse to encode real reversibility and responsibility. actor. Shared-model security The relationship model Provenance, authority becomes a high-value or acceptance can be target. forged. Plural humans There is rarely one Operator preference human interest or erases affected authority. stakeholders. Absent stakeholders Affected people may not Coherent interaction be participants. remains unjust or incomplete. Behavior vs intent Observed behavior is System infers intention not self-interpreting. from hesitation, clicks or abandonment. Right to opacity Some human state should Mutual legibility remain tentative, becomes compulsory private or uncommitted. legibility. Forgetting Persistent memory can Stale assumptions gain preserve obsolete or durable authority. revoked state. Success criteria Legibility is not Theory becomes valuable merely because unfalsifiable interface it exists. rhetoric. ----------------------------------------------------------------------- # 2. Central correction to the original model NOT:\ Human Model \<-\> Shared Model \<-\> Machine Model\ \ MORE PRECISELY:\ Human state(s) \> Relationship State \<\ Machine state(s) /\ \ The shared object is not a merged mind.\ It is the explicit computational state of the relationship. +-----------------------------------------------------------------------+ | **Primary refinement** | | | | HCML should optimize for inspectable difference and correctable | | relationship state, not for making human and machine internal models | | converge. | +=======================================================================+ +-----------------------------------------------------------------------+ # 3. Hard boundaries - Human state represented in the system must always have source and authority provenance. - Machine assertions must be distinguishable from machine observations and machine authority. - Unknown, unresolved, disagreed, revoked, hidden, absent and unauthorized are distinct states. - Human-facing claims require human evidence; architectural representability is not behavioral validation. - A relationship state may coordinate actors without claiming to contain their complete beliefs, motives or understanding. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/09-relationship-state-model.md (167 lines, 6.7 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship State Model The explicit computational state of a human--computer relationship Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **Relationship State is the proposed central primitive: a versioned, scoped, provenance-bearing record of what was asked, understood, permitted, inferred, evidenced, executed, corrected, accepted, revoked, and left unresolved between participants.** # 1. Formal shape RelationshipState {\ scope\ participants\[\]\ intentRepresentations\[\]\ interpretations\[\]\ constraints\[\]\ authorityGrants\[\]\ evidence\[\]\ uncertainty\[\]\ disagreements\[\]\ commitments\[\]\ candidateActions\[\]\ executions\[\]\ observations\[\]\ corrections\[\]\ revocations\[\]\ unresolved\[\]\ history\ version\ } # 2. State classes ----------------------------------------------------------------------- **Class** **Meaning** **Who may establish** ----------------------- ----------------------- ----------------------- Declared Explicitly stated and Named human/system committed by an authority. authorized participant. Inferred System interpretation Inference mechanism; or model-derived never self-promotes. conclusion. Observed Recorded event or state Observation authority. from an authoritative sensor/tool/runtime. Contract-relative True only under a Contract authority. declared comparison, policy or project contract. Candidate Proposed but not Any permitted proposer. accepted as governing state. Accepted Accepted for a bounded Acceptance authority. scope. Committed Frozen or Commit authority. execution-governing state. Revoked Formerly active but no Revocation authority. longer authorized. Unresolved Material difference not No one; it is yet adjudicated. explicitly retained. Historical-only Preserved for Lifecycle policy. provenance but excluded from current decision state. ----------------------------------------------------------------------- # 3. Relationship state is scoped The same person and same computational system may have different relationship states simultaneously. Authority, memory, persistence, privacy, and acceptable automation are properties of the relationship context, not global properties of either participant. Project A: AI may modify source but may not deploy.\ Project B: AI is read-only.\ Decision C: AI may advise but human owns weights and exit.\ Private conversation: no durable project state unless explicitly promoted. # 4. Invariants - No inference silently becomes declared human intent. - No capability silently becomes authority. - No observation automatically becomes interpretation. - No machine output self-promotes from candidate to accepted. - No revocation deletes provenance needed to explain past execution unless deletion policy explicitly requires it. - No interface projection may make hidden state indistinguishable from nonexistent state when the distinction is consequential. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/10-temporal-consistency-correction-and-forgetting.md (159 lines, 7.1 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Temporal Consistency and Correction Keeping intent, interpretation, execution, and memory synchronized over time Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **Human--computer relationships are distributed systems in miniature: intent can change while execution is in flight, observations can arrive late, interpretations can be stale, and multiple actors can update overlapping state.** # 1. Versioned interaction state t0 Intent v7 declared\ t1 Interpretation v7.1 proposed\ t2 Action based on v7.1 authorized\ t3 Human correction creates Intent v8\ t4 v7.1 action still executing\ t5 system must reconcile or stop; it may not pretend v7 remains current # 2. Consistency states -------------------------------------------------------------------------- **State** **Definition** **Expected behavior** ----------------------- -------------------------- ----------------------- Current Interpretation/execution Proceed. references latest governing relationship version. Stale-but-safe Older version in use, but Disclose and converge. protected invariants remain satisfied. Conflicted Two authorized updates Freeze consequential cannot both govern. action; surface conflict. Superseded New state explicitly Old state becomes replaces earlier state. historical-only. Revoked Authority or permission Prevent new actions; withdrawn. stop/rollback where contract requires. Unknown consistency System cannot prove which Stop at protected state governs. boundary. -------------------------------------------------------------------------- # 3. Correction economics Correctability is not sufficient if correction consumes more human effort than the automation saves. HCML therefore treats repair burden as a first-class evaluation dimension. ----------------------------------------------------------------------- **Metric** **Question** ----------------------------------- ----------------------------------- TTDM Time to Detect Misalignment: how long before the person or system notices the interpretation diverged? TTCI Time to Correct Interpretation: how long to establish the corrected shared state? Repair Turns How many interaction cycles are required? Correction Persistence Does the correction survive later context changes and sessions where it should? Repeated Misinterpretation Rate How often does a previously corrected mismatch recur? Supervision Load How much ongoing human attention is required to keep the system within bounds? ----------------------------------------------------------------------- # 4. Lifecycle and forgetting - Every durable state should define retention, expiry, supersession and deletion semantics. - Preferences should not become permanent merely because they were once useful. - Revoked authority must propagate to future action planning. - Historical evidence may need retention even when operational authority expires; privacy policy determines when deletion overrides auditability. - Ephemeral exploration should remain possible without automatic conversion into project memory. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/11-plural-actors-delegation-and-opacity.md (155 lines, 7.1 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Plural Actors, Delegation, and the Right to Opacity Authority when more than one human or computational actor shares the relationship Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The dyad "human ↔ computer" is a useful teaching diagram but an inadequate operating model. Real systems include multiple humans, services, models, policies, maintainers, institutions, and affected non-users.** # 1. Participant topology Humans: operator / author / maintainer / approver / regulator / affected non-user\ Computational actors: LLM / compiler / policy engine / database / runtime / sensor / evaluator\ \ Relationship State does not merge them.\ It records actor-relative claims, authority, evidence and consequence. # 2. Delegation graph ------------------------------------------------------------------------ **Capability** **Example authority** **Default risk posture** ----------------------- ------------------------ ----------------------- Inspect Read Low source/evidence/state. Propose Create candidate Low interpretation/action. Simulate Evaluate a hypothetical Low--medium world without mutation. Draft Modify non-authoritative Medium artifact. Execute reversible Perform action with Medium defined rollback. Execute irreversible Commit external High consequence. Accept Promote candidate to High governing state. Delegate Grant authority to Very high another actor. Revoke Withdraw prior Very high authority. ------------------------------------------------------------------------ # 3. Affected but absent participants A system may be mutually legible with its active operator and still fail people who are affected by its actions but are not present in the interaction. HCML therefore distinguishes represented stakeholders from affected stakeholders and requires explicit policy for whose interests and rights must constrain the relationship state. # 4. Right to opacity +-----------------------------------------------------------------------+ | **Mutual legibility is not compulsory legibility** | | | | Not every human thought, preference, hesitation, contradiction, or | | exploratory statement should become durable structured state. Human | | participants require room for privacy, ambiguity, tentative thought, | | revision, and non-persistence. | +=======================================================================+ +-----------------------------------------------------------------------+ ----------------------------------------------------------------------- **Human-state status** **Persistence** **Authority** ----------------------- ----------------------- ----------------------- Ephemeral Discard after None unless explicitly interaction/window. promoted. Tentative May be retained Does not govern temporarily with consequential action. visible uncertainty. Private Not exposed beyond Cannot be repurposed by declared audience. other actors. Declared Durable statement with Scope-dependent. provenance. Committed Frozen governing state. Authoritative within declared scope. ----------------------------------------------------------------------- # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/12-typed-uncertainty-and-disagreement.md (134 lines, 5.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Typed Uncertainty and Inspectable Disagreement Preventing confidence, evidence, interpretation, and consensus from collapsing into one score Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **A shared relationship model becomes dangerous if it converts all uncertainty into a single confidence number or treats disagreement as noise to be averaged away.** # 1. Uncertainty taxonomy ----------------------------------------------------------------------- **Type** **Example** **What it does not mean** ----------------------- ----------------------- ----------------------- Predictive probability Model estimates event Source is 70% reliable. likelihood at 0.7. Epistemic uncertainty Model lacks sufficient Outcome is random. information. Measurement precision Sensor/OCR estimate has Interpretation is bounded error. correct. Source reliability Evidence source has Claim is false. known limitations. Consensus dependence Multiple models share Independent sources/training confirmation. assumptions. Interpretation System confidence in Human endorsed the confidence mapping utterance to interpretation. intent. Human confidence Person reports Decision is accurate. confidence in a decision. Policy certainty Rule deterministically Rule is normatively applies. correct. ----------------------------------------------------------------------- # 2. Disagreement as state Human intent representation A\ System interpretation B\ Policy requirement C\ Observed world state D\ \ Do not collapse -\> one synthetic answer.\ Retain -\> A, B, C, D + their relationships + unresolved conflicts. # 3. Minimum uncertainty record UncertaintyRecord {\ subject\ uncertainty_type\ source\ method\ value_or_class\ calibration_status\ scope\ valid_at\ provenance\ } # 4. Projection rule Interfaces should project only the uncertainty needed for the current task while preserving access to provenance and deeper state. The objective is legibility bandwidth, not maximal information density. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/13-relationship-state-threat-model.md (155 lines, 6.5 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship-State Threat Model Security, manipulation, provenance, and authority attacks against the shared model Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **If relationship state becomes the place where intent, evidence, authority and acceptance are coordinated, then compromising that state can be more damaging than modifying an ordinary interface or chat transcript.** # 1. Threat classes ---------------------------------------------------------------------------- **Threat** **Example** **Required defense** ----------------------- ----------------------- ---------------------------- Intent forgery System records inferred Typed provenance + promotion preference as gate. user-declared. Authority escalation Adapter converts "can Capability/authority propose" into "can separation; deny by default. execute." Evidence laundering AI-produced claim Source class + immutable appears as external lineage. observation. Confidence laundering Constant or Typed uncertainty; allow uncalibrated score absence. presented as measured confidence. History rewriting Prior decision changed Append-only/tamper-evident after outcome. history. Conflict erasure Disagreeing sources Preserve contradictory merged into one value. records. Projection deception UI hides Loss-aware projection unavailable/blocked contract. state so it appears nonexistent. Stale-intent execution Action continues after Version binding + revocation governing intent propagation. changed. Cross-context leakage Preference from one Scope-bound memory and relationship reused in authority. another. Model-side prompt Untrusted content Tool/result isolation; fixed injection modifies governing schemas; explicit authority state. path. Stakeholder omission Operator-only model Stakeholder/rights ignores affected constraints in policy layer. non-user. ---------------------------------------------------------------------------- # 2. Security invariants - Every state mutation names actor, authority, scope, prior version and resulting version. - Adapters may reduce authority but may not expand it. - Promotion and execution are distinct operations. - Disagreement is data and must not be normalized away without a named rule. - Lossy projections disclose what they omit or transform. - Sensitive human state has explicit retention and audience policy. - Unknown or unverifiable provenance blocks protected promotion. # 3. Audit object RelationshipEvent {\ event_id\ relationship_id\ actor_id\ action\ authority_ref\ input_refs\[\]\ previous_version\ resulting_version\ evidence_refs\[\]\ timestamp_or_order\ integrity_digest\ } # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/14-measurement-and-empirical-validation-program.md (187 lines, 8.8 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** HCML Measurement and Empirical Validation Program How to determine whether mutual legibility actually helps people Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The research should fail cleanly if explicit relationship state adds complexity without improving prediction, correction, calibration, agency, coordination, recovery, or task outcomes.** # 1. Primary constructs ----------------------------------------------------------------------- **Construct** **Operational **Candidate measure** question** ----------------------- ----------------------- ----------------------- Behavioral Can the human predict Prediction accuracy / predictability what the system will do calibration. next? Interpretation accuracy Does the system Human-confirmed correctly characterize classification explicitly declared accuracy. intent? Correction efficiency Can mismatches be TTDM, TTCI, repair repaired quickly and turns, recurrence. persistently? Trust calibration Does reliance track Calibration error, actual system over-/under-reliance. competence? Agency legibility Can the person identify Authority what they can stop, identification override, revoke or accuracy + action delegate? success. Provenance Can users distinguish Source-class comprehension observation, inference, identification. policy and recommendation? Coordination Do human and system Task success, errors, complete joint tasks handoff failures. more reliably? Recovery Can the relationship Time-to-recovery, recover after a system retained context, error? repeated-error rate. Legibility burden How much Time, interruptions, cognitive/supervisory workload, abandonment. cost does the added structure create? Plural fairness Are affected Constraint coverage / stakeholder constraints violation rate; represented and domain-specific human respected? review. ----------------------------------------------------------------------- # 2. Core experiment families ----------------------------------------------------------------------- **Study** **Comparison** **Falsification signal** ----------------------- ----------------------- ----------------------- Intent interpretation Natural-language-only No reduction in vs explicit misunderstanding or intent/constraint repair cost. state. Authority comprehension Conventional Users remain unable to permissions vs visible predict/override system delegation graph. actions. Provenance Flat answer vs typed No calibration gain or evidence/provenance increased over-trust. view. Temporal correction Chat-history context vs No reduction in versioned relationship stale-intent execution state. or repeated corrections. Disagreement Merged answer vs Conflict view harms inspectable conflict decisions without state. measurable compensating benefit. Legibility bandwidth Full state dump vs Projection either hides task-relative consequential state or projection. offers no workload benefit. Longitudinal memory Persistent state vs Scoped model does not scoped reduce stale lifecycle/forgetting. preference/authority errors. ----------------------------------------------------------------------- # 3. Claim ladder Representable != Implemented != Tested != Human-observed != Empirically validated != Generalizable A system can successfully implement relationship-state semantics while the human-facing theory fails. That is a valid research result and should narrow the theory rather than be reframed as success. # 4. Stop conditions - Added relationship-state complexity materially increases task time or error without compensating benefit. - Users cannot correctly interpret provenance/authority despite interface refinement. - Correction cost remains equal to or worse than conventional interaction. - The model requires inferential access to human state that cannot be ethically or reliably measured. - Simpler interface or workflow mechanisms produce equivalent outcomes with lower complexity. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/15-relationship-state-research-roadmap.md (154 lines, 7.2 KiB) ======================================================================== **HUMAN--COMPUTER MUTUAL LEGIBILITY** Relationship State Research Roadmap A bounded path from implemented mechanisms to a falsifiable HCML theory Working research specification · August 2026 **Status boundary** This document extends the HCML working theory using the supplied project corpora. Mechanisms implemented in those projects are treated as engineering evidence. Claims about human understanding, trust, agency, coordination, or behavioral benefit remain hypotheses unless independently validated. **The next step should not be another universal abstraction. It should be a sequence of narrow experiments that force the relationship-state model against cases capable of breaking it.** # 1. Workstreams ------------------------------------------------------------------------------- **Phase** **Deliverable** **Promotion gate** ----------------------- ----------------------- ------------------------------- R0 Canonical Can encode existing project RelationshipState examples without invented schema and vocabulary. facts. R1 Conversation Inference never self-promotes; intent/provenance corrections are versioned. adapter. R2 Delegation graph + Capability and authority remain protected-action separable in tests. evaluator. R3 Typed uncertainty + Conflicting evidence survives disagreement ledger. projection and round-trip. R4 Temporal consistency Stale/revoked intent blocks engine. protected execution. R5 Relationship event Historical explanation and log + scoped deletion both work. lifecycle/forgetting. R6 Threat-model red-team Forgery/escalation/laundering corpus. tests fail closed. R7 Two controlled human At least one measurable HCML studies. benefit or principled narrowing. R8 Longitudinal Correction persistence and correction/memory stale-state cost measured. study. R9 Cross-domain Same relation primitives replication. survive at least two materially different domains. R10 Theory promotion Promote, narrow, rename, or decision. reject based on retained evidence. ------------------------------------------------------------------------------- # 2. First prototype +-----------------------------------------------------------------------+ | **Recommended next experiment** | | | | Build a small relationship-state layer over one existing | | conversational/agent workflow. Capture only intent representation, | | interpretation, authority, evidence, uncertainty, correction, version | | and execution reference. Compare it against the same workflow using | | chat history alone. | +=======================================================================+ +-----------------------------------------------------------------------+ # 3. What not to build yet - No universal ontology of human meaning. - No cross-project global user model. - No automatic behavioral inference promoted as intent. - No scalar "mutual legibility score." - No assumption that more visible state is always better. - No autonomous promotion of machine interpretations. - No requirement that existing projects adopt the theory before empirical value is demonstrated. # 4. Decision rule Keep the concept only where explicit relationship state\ reduces consequential guessing between participants.\ \ If a simpler representation achieves the same result,\ use the simpler representation. # Source basis and claim boundary The architecture below is a synthesis. The supplied projects demonstrate individual mechanisms, not the full HCML theory. Human-facing outcomes therefore remain explicitly unvalidated unless separately measured. ----------------------------------------------------------------------- **Corpus** **What it supports** ----------------------------------- ----------------------------------- FCI v0.5.0 Separates semantics, projection, interpretation, measurement and evidence; formalization makes uncertainty inspectable rather than eliminating it. Fundamental v0.10.0 Maintains relational state, snapshots, diffs, diagnostics, projection contracts and explicit refusal to invent unsupported findings. IEPE v0.2.0 Represents intent, authority, evidence, negative results, blockers, promotion and evolving conversation/project state explicitly. PDP v1.3.0 Separates machine argument from human weight/stake/exit authority and structurally preserves frozen decisions and append-only audit. Scene Builder v0.1.0 Shows the need for shared operational state across human, UI, CLI and AI actors without privileging one interface path. Re-Mesh v0.1.0 Carries confidence, provenance, inferred affordances and transformation history with assets instead of forcing downstream reconstruction. Comic OCR Rust Keeps machine output as candidate state, preserves provenance, and explicitly drops fabricated confidence rather than laundering it into the graph. ----------------------------------------------------------------------- ======================================================================== ## FILE: Human-Computer-Mutual-Legibility-Research-Corpus-v2/README.md (35 lines, 2.5 KiB) ======================================================================== # Human–Computer Mutual Legibility — Working Research Corpus This corpus formalizes a recurring concept observed across the supplied project implementations: systems become more trustworthy and capable when consequential human intent and machine state are made mutually legible through explicit representations of intent, evidence, authority, uncertainty, provenance, correction, and consequence. ## Documents - `00-program-charter.docx` — program definition, scope, non-goals, success ladder. - `01-theory-of-mutual-legibility.docx` — conceptual theory and human–machine relationship model. - `02-evidence-across-implementations.docx` — cross-project evidence and limitations. - `03-shared-computational-model-architecture.docx` — technical architecture and state model. - `04-mutual-interaction-authority-protocol.docx` — interaction, correction, authority, and negotiation protocol. - `05-research-validation-program.docx` — hypotheses, experiments, metrics, falsification, and claim boundaries. - `06-publication-framework.docx` — structure and claim discipline for the long-form article. - `07-design-principles-implementation-heuristics.docx` — reusable engineering principles and review checklist. ## Working term **Human–Computer Mutual Legibility (HCML)** is provisional. It does not imply mutual consciousness or equal agency. It denotes an engineered condition in which humans can inspect consequential machine state and machines receive explicit representations of consequential human intent, authority, constraints, correction, and acceptance. ## Evidence boundary The project corpora provide architectural evidence and implemented mechanisms. They do not yet empirically establish that HCML improves trust, understanding, safety, or performance for human users. Those claims are framed as hypotheses in the research program. ## Relationship State extension The second HCML document family refines the initial “shared model” thesis into an explicit **Relationship State** model and records the unresolved theory, security, temporal, plural-actor, uncertainty, privacy, and empirical-validation gaps. - `08-open-gaps-and-missing-theory.docx` - `09-relationship-state-model.docx` - `10-temporal-consistency-correction-and-forgetting.docx` - `11-plural-actors-delegation-and-opacity.docx` - `12-typed-uncertainty-and-disagreement.docx` - `13-relationship-state-threat-model.docx` - `14-measurement-and-empirical-validation-program.docx` - `15-relationship-state-research-roadmap.docx` ======================================================================== ## FILE: LICENSE (21 lines, 1.0 KiB) ======================================================================== MIT License Copyright (c) 2026 Zach Shallbetter Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ======================================================================== ## FILE: README.md (64 lines, 6.0 KiB) ======================================================================== # Human–Computer Mutual Legibility HCML is a research corpus built around one working thesis: people and software work better together when consequential human intent and machine state are both made explicit and inspectable. It sets out a theory, an architecture, an interaction protocol and a validation program, and it says plainly that its claims about human outcomes are still hypotheses. **Identifier:** `hcml` · **Corpus version:** 2.0.0 (research corpus v2 plus the Relationship State extension) · **Status:** Research, August 2026 ## What it does The corpus defines mutual legibility as an engineered condition. A person can inspect what a system observed, inferred, found relevant, changed or is allowed to do. The system receives explicit representations of the person's intent, constraints, authority, corrections, acceptance and exit conditions. It does not imply shared consciousness, shared interpretation or equal agency. The first eight documents (00–07) build the program: charter, theory, evidence drawn from existing projects, a shared-model architecture, an interaction and authority protocol, a validation program, a publication framework and design heuristics. The second family (08–15) refines the "shared model" idea into an explicit Relationship State model and records the open problems. ## Features - A three-model framing: the human model, the machine model and the shared computational model, where the shared model holds only what is explicit enough to coordinate action. - A mutual legibility loop in which disagreement between the models is a representable, often informative state. - A mutual interaction and authority protocol with interaction phases, human and machine roles, correction classes, anti-patterns and a negotiability test. - A `RelationshipState` structure covering participants, intent, interpretations, constraints, authority grants, evidence, uncertainty, disagreements, commitments, actions, corrections, revocations and history. - Treatment of time, correction and forgetting; plural actors and delegation; typed uncertainty; and a threat model for relationship state. - A validation program with hypotheses, measurement families, core experiments, a claim taxonomy and negative results worth keeping. - A "source basis and claim boundary" section at the end of each document. ## How it works The core proposition is that many failures blamed on bad interfaces, unreliable AI or poor context come from one side having to infer consequential state that the other side could have stated. The corpus traces a shift from people instructing machines, through interfaces and feedback, to a shared computational model of intent, evidence, authority and uncertainty that both sides can read and correct, without letting the machine quietly turn its interpretation into the person's intent. The evidence document (02) draws on mechanisms already built in other projects and separates what they demonstrate from what they do not. The validation program (05) turns the remaining claims into testable hypotheses. Documents 08 and 13 hold the open gaps and the threat model, and the agent contract in `.agents/AGENTS.md` requires that these negative results are kept. In the wider protocol stack, HCML is the research program the other protocols would serve if it holds. It is the least settled entry in the register. ## What this explores - Whether human intent, authority and correction can be represented explicitly enough for a machine to act on without guessing. - How to model disagreement, uncertainty and revocation as first-class state instead of errors. - The security, privacy and temporal risks of keeping a persistent record of a human–machine relationship. - How to hold a research program to the distinction `Documented != Implemented != Tested != Empirically Validated`. ## Contents | Path | What it holds | | :--- | :--- | | [`Human-Computer-Mutual-Legibility-Research-Corpus-v2/`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/) | All sixteen documents, 00–15, in Markdown, with a README | | [`HCML-Relationship-State-Extension/`](HCML-Relationship-State-Extension/) | Documents 08–15 on their own; identical to the same files in the corpus folder | | [`.agents/`](.agents/) | Agent operating contract and generated full-text bundles | | [`scripts/gen-llms.py`](scripts/gen-llms.py) | Regenerates the `.agents/` bundles | | [`package.json`](package.json) | Package metadata | The README inside the corpus folder lists the documents with `.docx` names; the files in this repository are the Markdown versions. ## How to read this 1. [`00-program-charter.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/00-program-charter.md): definition, scope, non-goals and the working thesis. 2. [`01-theory-of-mutual-legibility.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/01-theory-of-mutual-legibility.md): the three models, the loop and the core distinctions. 3. [`02-evidence-across-implementations.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/02-evidence-across-implementations.md): what existing projects show and what they do not. 4. [`04-mutual-interaction-authority-protocol.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/04-mutual-interaction-authority-protocol.md) and [`09-relationship-state-model.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/09-relationship-state-model.md): the protocol and the formal state. 5. [`05-research-validation-program.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/05-research-validation-program.md) and [`08-open-gaps-and-missing-theory.md`](Human-Computer-Mutual-Legibility-Research-Corpus-v2/08-open-gaps-and-missing-theory.md): how the claims would be tested and what is still missing. Status: a research corpus. It informs; it does not prescribe. The implemented mechanisms it cites come from other projects, and it does not claim that HCML improves trust, understanding, safety or performance for people. Those are framed as hypotheses. ## License MIT © Zach Shallbetter Built by [Zach Shallbetter](https://zachshallbetter.com). ======================================================================== ## FILE: package.json (8 lines, 0.5 KiB) ======================================================================== { "name": "human-computer-mutual-legibility", "version": "2.0.0", "description": "Human-Computer Mutual Legibility (HCML) research corpus, v2 + Relationship State Extension. Research corpus: informs, does not command; its empirical claims are unvalidated by its own admission. Consumed read-only as a pinned reference.", "license": "UNLICENSED", "private": true, "files": ["Human-Computer-Mutual-Legibility-Research-Corpus-v2/", "HCML-Relationship-State-Extension/"] } ======================================================================== ## FILE: scripts/gen-llms.py (208 lines, 6.5 KiB) ======================================================================== #!/usr/bin/env python3 """ gen-llms.py — Agent-First Publishing Architecture & Context Corpus Exporter for Human-Computer Mutual Legibility (HCML). Generates versioned, abbreviated llms index and full corpus files in the `.agents/` directory: .agents/llms-hcml-v.txt .agents/llms-full-hcml-v.txt """ import os import sys import re import json import glob import subprocess from datetime import datetime ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) AGENTS_DIR = os.path.join(ROOT_DIR, ".agents") def get_version(): try: tag = subprocess.check_output( ["git", "describe", "--tags", "--abbrev=0"], cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True ).strip() if tag: return tag.lstrip("v") except Exception: pass return "0.2.0" VERSION = get_version() ABBR = "hcml" DATE = datetime.now().strftime("%Y-%m-%d") EXCLUDED_DIRS = { "_scripts", "_references", "_production", "node_modules", "target", ".git", ".github", ".agents", ".vscode", ".claude", ".cache", "dist", "build", "tmp", "temp", } EXCLUDED_FILE_SUBSTRINGS = { "-lock.json", ".lock", "pnpm-lock.yaml", "yarn.lock", "package-lock.json", ".DS_Store", ".map", ".zip", } ALLOWED_EXTS = {".ts", ".tsx", ".js", ".jsx", ".json", ".md", ".toml", ".rs", ".sql"} def is_excluded_dir(dir_name): lower = dir_name.lower() if dir_name in EXCLUDED_DIRS or lower in EXCLUDED_DIRS: return True if dir_name.startswith(".") and dir_name != ".agents": return True return False def read_file(file_path): try: with open(file_path, "r", encoding="utf-8") as f: return f.read() except Exception: return "" def is_excluded_file(file_name): lower = file_name.lower() for sub in EXCLUDED_FILE_SUBSTRINGS: if sub in file_name: return True return False def normalize_whitespace(text): return re.sub(r'\n{3,}', '\n\n', text) def read_source_files(): entries = [] for root, dirs, files in os.walk(ROOT_DIR): dirs[:] = [d for d in dirs if not is_excluded_dir(d)] for f in files: ext = os.path.splitext(f)[1] if ext in ALLOWED_EXTS and not is_excluded_file(f): full_path = os.path.join(root, f) rel_path = os.path.relpath(full_path, ROOT_DIR) content = read_file(full_path) entries.append((rel_path, content)) return sorted(entries, key=lambda x: x[0]) def categorize_files(source_files): categories = { "Core Research Corpus (v2)": [], "Relationship State Extensions": [], "Other Modules": [] } for rel, src in source_files: line_count = len(src.splitlines()) size_kib = round(len(src.encode('utf-8')) / 1024, 1) item = (rel, line_count, size_kib) if "Research-Corpus" in rel or rel.startswith("Human-Computer"): categories["Core Research Corpus (v2)"].append(item) elif "Relationship-State" in rel or rel.startswith("HCML-"): categories["Relationship State Extensions"].append(item) else: categories["Other Modules"].append(item) return categories def main(): if os.path.exists(AGENTS_DIR): for old_file in glob.glob(os.path.join(AGENTS_DIR, "llms*.txt")): try: os.remove(old_file) except Exception: pass else: os.makedirs(AGENTS_DIR, exist_ok=True) agents_md = read_file(os.path.join(AGENTS_DIR, "AGENTS.md")) source_files = read_source_files() categorized = categorize_files(source_files) total_lines = sum(len(src.splitlines()) for _, src in source_files) manifest_lines = [ f"# Human-Computer Mutual Legibility (HCML) — Agent-First Manifest", f"> Version: v{VERSION} | Generated: {DATE} | Total Modules: {len(source_files)} files | Total Lines: {total_lines:,} lines", "", "## Core Architecture & Governance", "- [.agents/AGENTS.md](.agents/AGENTS.md): Agent Operating Contract", "", ] for cat, items in categorized.items(): if items: manifest_lines.append(f"## {cat} ({len(items)} files)") for rel, lcnt, size in items: manifest_lines.append(f"- [{rel}]({rel}) ({lcnt} lines, {size} KiB)") manifest_lines.append("") manifest_content = "\n".join(manifest_lines) + "\n" sep = "=" * 72 def banner(title, info=""): extra = f" [{info}]" if info else "" return f"\n{sep}\n## {title}{extra}\n{sep}\n\n" full_parts = [ f"# HUMAN-COMPUTER MUTUAL LEGIBILITY (HCML): CONSOLIDATED RESEARCH & SPECIFICATION CORPUS\n", f"Version: v{VERSION} ({DATE}) | Modules: {len(source_files)} | Total Lines: {total_lines:,}\n\n", f"TABLE OF CONTENTS & SUBSYSTEM SUMMARY:\n" ] for cat, items in categorized.items(): if items: full_parts.append(f" - {cat}: {len(items)} files\n") full_parts.append(f"\n{sep}\n\n") if agents_md: full_parts.append(banner("FILE: .agents/AGENTS.md") + agents_md + "\n") for cat, items in categorized.items(): if items: full_parts.append(banner(f"SUBSYSTEM: {cat.upper()} ({len(items)} files)")) for rel, src in source_files: if any(r == rel for r, _, _ in items): lcnt = len(src.splitlines()) size_kib = round(len(src.encode('utf-8')) / 1024, 1) full_parts.append(f"--- FILE: {rel} ({lcnt} lines, {size_kib} KiB) ---\n{src}\n\n") full_content = normalize_whitespace("".join(full_parts)) # Write ONLY versioned abbreviated outputs (no unversioned files) versioned_manifest_path = os.path.join(AGENTS_DIR, f"llms-{ABBR}-v{VERSION}.txt") versioned_full_path = os.path.join(AGENTS_DIR, f"llms-full-{ABBR}-v{VERSION}.txt") with open(versioned_manifest_path, "w", encoding="utf-8") as f: f.write(manifest_content) with open(versioned_full_path, "w", encoding="utf-8") as f: f.write(full_content) full_kib = round(len(full_content.encode("utf-8")) / 1024) print( f"gen-llms: generated {os.path.basename(versioned_manifest_path)} ({len(manifest_content)} bytes) and {os.path.basename(versioned_full_path)} ({full_kib} KiB, {len(source_files)} source files included) [Version: v{VERSION}]" ) if __name__ == "__main__": main()