State what Modore is for, name its public surface, and freeze the Zoint seam - #82
Merged
Conversation
Three moves that had fallen a generation behind the code. The README led with "what your AI agents left behind" and gave the generic PC diagnostic equal billing. Neither sentence survived moraine: an orphaned trust root from a removed banking plugin and an orphaned worktree from a removed agent workspace are the same problem, and "AI" was never the boundary. The head now states the ontology -- durable local state that outlives the work, tool, or software that created it -- with "built for Macs shaped by AI-assisted development" as the audience line beneath it, and a Scope section fixes the rule every new capability is judged against. The diagnostic surface is declared maintained, not growing. The MCP vocabulary leaked implementation history: scree is a codename, hf_ is a vendor abbreviation, and a client calls these by string. Renamed in one pass while the consumer count is zero and no alias left behind -- an alias is a promise to support the old name forever, made to nobody: scree_report -> agent_state_report friction_scan -> operator_friction_report hf_orphans -> model_residue_report file_access -> agent_file_access mcp_hygiene and system_scan_summary already say what they do, and uninstall_residue_report landed under its final name. Internal filenames and handler names keep their codenames; the split between what a client calls and what a maintainer greps is the point. The bind output becomes the frozen seam: schema "modore.agent-state-snapshot", schemaVersion 1, generatedAt, with the contract documented and three semantic limits stated as part of it -- complete means conclusively classified rather than totally observed, the fingerprint is a same-or-changed check rather than provenance, and a snapshot is historical evidence that never authorizes destruction. The reference fixture is generated from a real run and pinned; the Swift consumer refuses a schemaVersion it does not know instead of best-effort parsing it, which is the contract's own versioning rule enforced where misreading would happen.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three moves that had fallen a generation behind the code, done as one
cleanup so the product sentence, the public vocabulary, and the external
contract stop disagreeing with what the repository actually does.
1. Scope
The README led with "what your AI agents left behind" and gave the
generic PC diagnostic equal billing. Neither survived moraine: an
orphaned trust root from a removed banking plugin and an orphaned
worktree from a removed agent workspace are the same problem. The head
now states the ontology — durable local state that outlives the work,
tool, or software that created it — with the AI-builder Mac as
audience, not filter. A Scope section fixes the in/out rule; the
diagnostic surface is maintained, not growing.
2. Public MCP vocabulary
Renamed in one pass while consumers number zero, no aliases:
scree_reportagent_state_reportfriction_scanoperator_friction_reporthf_orphansmodel_residue_reportfile_accessagent_file_accessmcp_hygiene,system_scan_summary,uninstall_residue_reportunchanged. Internal filenames and handlers keep their codenames — the
split between what a client calls and what a maintainer greps is the
point.
3. The seam, frozen
bind/bind-alloutput is nowmodore.agent-state-snapshotv1:schema+schemaVersion+generatedAton the existing shape,contract in
docs/agent-state-snapshot-v1.mdwith three semantic limitsstated as part of it (complete = conclusively classified, fingerprint =
same-or-changed check, snapshot ≠ destructive authorization). Reference
fixture generated from a real run and pinned; the Swift consumer refuses
an unknown
schemaVersioninstead of best-effort parsing.Zoint's consumer half landed separately (
zoint@d9e3f2b): fixture copy,byte-for-byte evidence preservation, version refusal, and
emptinessIsAFindingas the only sanctioned reading of an empty list.Verification
Python 604 · MothballCore 120 · Modore strict build clean · Zoint 57.