export: emit mecatl artefacts in Claude-Code-shaped layout, so leaving is as cheap as arriving
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
export: emit mecatl artefacts in Claude-Code-shaped layout, so leaving is as cheap as arriving
Sub-issue of the portability epic (#410). Independent of A–D. This is the credibility item — the
parent's claim that adopting mecatl is a reversible decision is not honest until this ships.
Problem
mecated import exists (ADR 0099); nothing goes
the other way. Every portability argument we make today is therefore one-directional, which is
exactly the shape of the lock-in we criticise in other harnesses. A platform team evaluating
mecatl will ask what the exit looks like, and the current answer is "hand-copy it."
Note the asymmetry that makes this cheaper than it sounds: because mecatl reads .claude/**
in place rather than converting it, a user who never opted into copying has nothing to export
— their config is already in the portable layout. Export matters for what mecatl itself
produced: sessions, and anything authored into .mecatl/** after arrival.
Scope to decide in review
- Sessions — emit a JSONL transcript a Claude Code / Codex install will open, from the
mecatl store. Lossy in the mirror-image way ADR 0099 is: mecatl-specific event records
(delegation, ask/verdict, memory) have no destination. Decide whether the target is a faithful
Claude-shaped transcript or a documented plain-text export, and say which in the ADR. - Skills / agent defs / commands / rules authored in
.mecatl/**— emit into
.claude/-shaped layout. Mostly a copy with front-matter mapping; the same sanitization,
confinement and no-overwrite guards as import. - Permissions —
.mecatl/settings*.yaml→ Claudesettings.json. Lossy in the opposite
direction from sub-issue C; every dropped or widened rule must be reported, and must never
widen silently (an unrepresentableaskbecomes absent, notallow). - Memory / soul / usermodel — mecatl-specific with no counterpart. Almost certainly
"not exported, reported"; confirm rather than assume.
Boundaries
- Never widens permission or trust posture in the exported artefacts. The fail-safe
direction on export is narrower, matching import's discipline. - No secrets. Same rule as everywhere in this epic.
- No overwrite, no symlink follow, destination confinement — ADR 0099's guards, reused.
- Offline, no credential, no daemon.
Acceptance
- A mecatl session exports to a transcript the target tool opens without error, and a
round-trip (import → export → import) neither duplicates nor loses user/assistant turns. - Exported permissions are never broader than the source; a test drives the effective decisions
both ways and asserts the export is a subset. - Every artefact class lands in exported / lossy-with-reason / not-exported, with the reason
string present — the same three-bucket report discipline as sub-issue A. - ADR covering export, its lossiness, and the never-widen rule;
docs/usage/mecated.mdand
user-docs updated.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ADR 0099 and the existing mecated import path to understand the sanitization, confinement, no-overwrite, and reporting guards to reuse. Define the export behavior for sessions, .mecatl/** artefacts, permissions, and memory-related data, then cover the round-trip and permission-subset acceptance cases. Update the export ADR, docs/usage/mecated.md, and user docs with lossiness and never-widen decisions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation, security, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100