stacklok / stacklok/mecatl

export: emit mecatl artefacts in Claude-Code-shaped layout, so leaving is as cheap as arriving

Open
#415 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

devex enhancement
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 → Claude settings.json. Lossy in the opposite
    direction from sub-issue C; every dropped or widened rule must be reported, and must never
    widen silently
    (an unrepresentable ask becomes absent, not allow).
  • 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.md and
    user-docs updated.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.