Skip to content

rosetta-archaeology plugin

Four-phase Project Archaeology pipeline. Takes an engagement discovery dossier and the Project Archaeology Manual v1.3 and produces a Digital Twin for that engagement — leaf KnowledgeDomain, three-layer Context Artifacts, DecisionTraces with the full v1.3 schema, an eleven-dimension readiness verdict, the delivery spine, a Site Package, and PromotionCandidate analysis — and applies it to the graph as twin.json through rosetta-app-server's twin:apply (ADR-PL-024).

  • Latest bundle: rosetta-archaeology-0.13.3.zip
  • Slash commands: /rosetta-archaeology:run-all (recommended for end-to-end processing), /rosetta-archaeology:survey, /rosetta-archaeology:excavate, /rosetta-archaeology:classify, /rosetta-archaeology:preserve (per-phase, fallback for incremental re-runs), /rosetta-archaeology:inheritance-tree-render (Phase 1 render skill — emits the inheritance-tree artifact; make inheritance-tree-render ENGAGEMENT=<key> is the equivalent in-repo invocation)
  • Skills: digital-twin-archaeology, inheritance-tree-render (first Option-B local render skill — canonical content inventory + inheritance-tree renderer)
  • License: Proprietary — © 2026 Keenan Vision LLC (see the repo LICENSE)

For the full method spec, unzip the bundle and read its inner README.md and skills/digital-twin-archaeology/SKILL.md. Source-of-truth methodology is the Project Archaeology Manual v1.3 — the plugin requires it as an upload on every phase.

What's new in v0.13.0 — the switch: twin.json through twin:apply is the delivery

The DT-RX-036 switch (platform E9-S2-WP1; ADR-PL-024 in effect) made the production graph the system of record for content and engagements, and db/seeds/ and db/engagements/ left main (the frozen baseline tag v0.27.0 keeps them). The --target=ingestion shape is now the only shape: Phase 4's twin.json carries the whole run, and Phase 4 applies it through twin:apply (rosetta_apply_engagement_twin, REST fallback) after the operator confirms the target, creating the engagement first if it does not exist. --publish applies in the run; without it Phase 4 asks. The bundle's db/engagements/<key>/ Cypher is the review stack twin.json is derived alongside: no phase writes it into a checkout, and nothing loads or commits it. Canonical content and existing engagements are read from the live graph (the rosetta MCP read tools; offline, a local graph restored from a content snapshot), and the Inheritance Tree's §1 is now the Canonical Content Inventory. --target=ingestion is a no-op for one release; --target=seeds is a hard fail that points at v0.27.0.

What's new in v0.12.0 — fixed phase timestamps and the whole run in the target's twin.json

Every run now writes one fixed RFC 3339 timestamp per phase emit, recorded in MANIFEST.md, in place of datetime() on the leaf's createdDate, the Context Artifact and DecisionTrace clocks, ProvenanceEntry capturedDate and the promotedDate Phase 4 now names; the leaf MERGE is create-only (platform E9-S1-WP17; app-server twin-apply-archaeology-lane.md Q-I-1). Under --target=ingestion, Phase 4's twin.json carries the whole run: the leaf, every property (uid, projectId and traceKey included), each DecisionTrace's promotion transition, the REFERENCES {via}, CA DEPENDS_ON, CA → leaf BELONGS_TO and DT GOVERNS edges and engagement.lifecycleStage, for an app-server that carries the archaeology lane (api 1.15.0). The default twin.json is unchanged.

What's new in v0.11.0 — ingestion target and a publishable default twin.json

Every run's Phase 4 twin.json now leaves PromotionCandidates out (twin:apply refuses the label, so one would refuse the whole document), and Phase 3 writes the canvas and readiness uids as the lowercased merge key, as twin:apply does, so --publish no longer fails on them (platform E9-S1-WP14; docs/decision-traces/e9-s1-wp2-plugin-ingestion.md Q-B-1).

--target=ingestion (off by default; manifest E9-S1-WP2) keeps the db/engagements/<key>/ Cypher and makes Phase 4's twin.json the run's ingestion payload on the twin:apply lane, and MANIFEST.md names every output the lane cannot carry yet (skills/digital-twin-archaeology/references/twin-document.md § "Ingestion target"). Before the DT-RX-036 switch the target submits only to a local app-server named by --ingest-url, after the operator confirms the graph target, and a run may not combine it with --publish; --publish alone keeps its ADR-PA-010 meaning. Without the flag a run is the 0.10.9 run apart from the two default-path changes above and the metamodel path (v1.17.0).

What's new in v0.9.1 — rebound client-edge emit + existing-client check

v0.9.1 (E3-S4-WP21; ratified in docs/decision-traces/client-engagement-linkage-remediation.md part (f)) fixes the §9.1 Client + Engagement block's edge emit and adds a Phase-1 existing-client check:

  • Rebound edge emit. The §9.1 template previously emitted a bare MERGE (cl)-[:HAS_ENGAGEMENT]->(eng); as its own statement, relying on cl/eng bindings carried over from prior semicolon-terminated statements. cypher-shell executes statements independently, so the MERGE actually created an anonymous, label-less node pair with the edge between them — the exact defect found on all 8 prod engagements. The edge emit now explicitly re-MATCHes both endpoints in its own statement (MATCH (cl:Client ...) MATCH (eng:Engagement ...) MERGE (cl)-[:HAS_ENGAGEMENT]->(eng) SET eng.clientUid = cl.uid), mirroring the already-correct BELONGS_TO_DOMAIN block.
  • Existing-client check (create-or-link). Before minting any MERGE (cl:Client ...) block, Phase 1 now inventories existing :Client nodes from the repo snapshot's db/engagements/*/00-domain.cypher plus the discovery dossier, presents the candidates to the operator, and records an explicit link-vs-create decision in survey-brief.md. Minting a new CL-<KEY> without that recorded decision is a Phase-1 gate failure.

What's new in v0.6.0 — spine + readiness emit

v0.6.0 implements ADR-PL-022 producer path 2 (ratified in docs/decision-traces/archaeology-delivery-spine-readiness-emit.md, 2026-06-10): the pipeline now emits the delivery spine and the readiness/d360 dimensions as engagement Cypher, closing the production empty-leg classes where the Engagement Canvas scorecard and the engagement-scoped spec-manifest compile read nothing unless the operator hand-compiled after the run.

  • Phase 3 emits 20-d360-dimensions.cypher (the ADR-PL-021 d360 advisory labels, schema 38–41 closed enums) and 21-engagement-readiness.cypher (the eleven-dimension verdict compiled to EngagementReadiness). The markdown verdict (classification-readiness-verdict.md) stays in the bundle as the human review surface; the Cypher is the canonical projection (C-2).
  • Phase 4 emits 30-delivery-spine.cypher — Wave → Epic → Sprint → Work Packet with the four locked ADR-PL-022 labels, Building-Block Epics 1:1 from the Context Artifacts (REALIZES_ARTIFACT by displayId), the terminal CA-less POV Complete Epic, gate-aligned Sprints, and acyclic DEPENDS_ON. Every node's purpose: is authored at emit review — the runtime never generates purpose boilerplate; a missing purpose halts the emit (stop-and-ask, not filler; INV-D28).
  • Both emits are canonical (no WARNING fallback) and load behind the INV-D20..D33 invariant gates. delivery-overlay.yaml remains the seed-input bridge for pre-existing overlays during the ADR-PL-022 one-cycle deprecation window.
  • v0.6.0 also lands the ratified CA five-field supersession (docs/decision-traces/archaeology-ca-five-field-supersession.md): every emitted ContextArtifact carries the five-field identity block plus uid per ADR-PL-020 / metamodel v1.9.0 §5.1.

Sibling to rosetta-research

The two plugins share a target repo but operate on different parts of the metamodel:

  • rosetta-research authors canonical content (projectId='SYSTEM') and submits it to the app-server's content:ingest API.
  • rosetta-archaeology authors engagement-scoped instances (projectId='<ENGAGEMENT-KEY>') and applies them through twin:apply.

Both can be installed simultaneously.

Installation

When you run claude from a rosetta-platform checkout, this plugin is auto-discovered via .claude/settings.json. The /rosetta-archaeology:* slash commands become available automatically (/rosetta-archaeology:run-all is the recommended entry point); first-run users get a "trust this folder?" prompt, subsequent runs are silent. No install step beyond the trust prompt.

This is the right path for plugin authoring and repo-internal use. Cowork upload (next section) is the right path for production archaeology sessions against an engagement dossier.

Claude (web / Cowork)

  1. Open a Cowork chat.
  2. Customize → Plugins → + → upload rosetta-archaeology-0.13.3.zip.
  3. Confirm /rosetta-archaeology:run-all and /rosetta-archaeology:survey appear in the slash-command palette.

Claude Code (CLI)

The bundle uses the standard plugin layout (.claude-plugin/plugin.json, commands/, skills/), so it can also be loaded as a local Claude Code plugin:

mkdir -p ~/.claude/plugins
unzip -o util/plugins/rosetta-archaeology/rosetta-archaeology-0.13.3.zip \
  -d ~/.claude/plugins/

Restart your Claude Code session and the /rosetta-archaeology:* commands become available. Refer to the Claude Code plugin documentation for marketplace-style registration if you prefer a managed install path.

The rosetta MCP connector (or REST access to the app-server) is needed: the phases read canonical content and existing engagements from the live graph through it, and Phase 4 applies twin.json through it.

Inputs every session expects

Drop these in the chat's uploads area before invoking the slash command:

Invocation Required uploads
end-to-end — /rosetta-archaeology:run-all repo zip + Manual + dossier (no per-phase bundles)
1 — /rosetta-archaeology:survey repo zip + Manual + dossier
2 — /rosetta-archaeology:excavate repo zip + Manual + dossier + rosetta-archaeology-<engagement>-phase1-*.zip
3 — /rosetta-archaeology:classify repo zip + Manual + dossier + Phase 2 bundle
4 — /rosetta-archaeology:preserve repo zip + Manual + dossier + Phase 3 bundle

/rosetta-archaeology:run-all is the recommended invocation for first-pass engagement processing. State accumulates through the Cowork conversation context across all four phases; only the final cumulative bundle is emitted. Halts at the first failing phase gate and emits a partial bundle reflecting work completed through the halt point.

Use the per-phase commands as a fallback for incremental re-runs when a run-all invocation surfaces an issue at a specific phase — upload the most recent per-phase bundle along with the standard inputs and re-run only the requested phase.

Where:

  • Repo zip is produced from a clean checkout: 
    cd ~/path/to/rosetta-platform
git archive --format=zip HEAD > /tmp/rp.zip
  • Manual is Project-Archaeology-Manual-v1.3.docx (or a zip of the manual). Required every phase.
  • Dossier is the engagement's discovery materials, either as *dossier*.zip or as the docs uploaded individually. Required every phase.
  • Prior-phase bundle is the most recent zip the plugin emitted. Required for Phases 2–4.

Each phase emits ONE cumulative zip; Phase 4's bundle contains everything from Phases 1–3 plus the partner-certification request and validation checklist. Re-upload the latest bundle as input to the next phase.

Phase 1 (Survey) ships a skill-rendered research/inheritance-tree.md artifact: a canonical content inventory (read from the live graph) plus inheritance-tree for the engagement's leaf KnowledgeDomain, with a deterministic §3 inheritance-candidate inventory that replaces the former ad-hoc grep survey step. The same artifact is produced in-repo by /rosetta-archaeology:inheritance-tree-render <key> or make inheritance-tree-render ENGAGEMENT=<key>, both of which dispatch to the inheritance-tree-render skill.

Delivering the twin

Phase 4 emits a VALIDATION-CHECKLIST.md, a PARTNER-CERTIFICATION-REQUEST.md and twin.json, and applies twin.json through twin:apply once the operator confirms the target (the app-server and the engagement uid). The bundle is the run's record: never unzip it into a checkout, and never commit or load its db/engagements/<engagementKey>/ Cypher (the review stack). MANIFEST.md records whether the twin was applied (twin_applied) and every failures[] entry; the bundle's VALIDATION-CHECKLIST.md has the checks before and after the apply (the static leaf check, the twin read-back, the scheduled read-only production gates).

After the apply, send PARTNER-CERTIFICATION-REQUEST.md to a senior partner architect for Gate 3 certification. After certification, the engagement team submits PromotionCandidates to Gate 4 governance review per ADR-PL-014 and ADR-PL-015. Both gates are out of scope for this plugin.

Methodological invariants (from Manual v1.3)

The plugin enforces these and will refuse to advance if they fail:

  • Trajectory and DecisionTrace are distinct (Ch. 4) — trajectories are raw, DecisionTraces are governed.
  • Existing configuration is evidence, not truth (Ch. 5).
  • Negative criteria are mandatory on every DecisionTrace (Ch. 7) — empty list is a hard fail.
  • alternativesConsidered ≥ 2 entries (Ch. 7).
  • Readiness, not goodness — Phase 3's eleven-dimension verdict is scoped to a specific intended action (Ch. 6).

ADR-PA-008 compliance

ADR-PA-008 establishes that plugin runtime outputs (manifests, validation checklists, eval invocation scripts, run logs, human-readable working notes) land at outputs/plugins/rosetta-archaeology/<engagementKey>/ in the repo root, gitignored, never auto-promoted.

Compliance landed in v0.2.0 and holds for all later releases. The bundle's internal layout places non-canonical artifacts under outputs/plugins/rosetta-archaeology/<engagementKey>/:

  • MANIFEST.md (cumulative across phases)
  • VALIDATION-CHECKLIST.md (Phase 4)
  • EVAL-INVOCATION-CHECKLIST.md (Phase 4)
  • research/{survey-brief,excavation-inventory,classification-readiness-verdict,preservation-promotion-analysis}.md
  • research/inheritance-tree.md — Phase 1 skill-rendered repo/seed inventory + inheritance-tree artifact (six sections, per-section rendered: flags, the §3 inheritance-candidate inventory, and the §Open Items «TBD-N» inventory); emitted by the inheritance-tree-render skill, sibling of survey-brief.md

Inside the bundle, the review stack and the Site Package keep their repo-shaped paths; neither is committed to the repo since the switch (ADR-PL-024):

  • the engagement Cypher review stack at db/engagements/<engagementKey>/
  • Site Package (including partner-validation/PARTNER-CERTIFICATION-REQUEST.md, which is part of the Manual Chapter 15 Site Package layout) at site-packages/<partnerKey>/<engagementKey>/

Run-identifier per ADR-PA-008 §Decision item 1 is <engagementKey>, shared by all four phases — the cumulative bundle accumulates research notes and replaces the manifest in place.

Constitutional alignment

The plugin operates within the rosetta-platform invariants (CLAUDE.md), as ADR-PL-024 amends them at the switch: the graph is the system of record for content, C-4 (Make is the user surface), C-5 (five-field identity), C-6 (ProvenanceEvent on every mutation), C-7 (producer-only — it imports nothing from rosetta-app-server and calls its API only at runtime).

It produces; you confirm. The plugin never invokes make, cypher-shell, mysql, docker, or any command on your machine, writes the graph only through twin:apply and the engagement create after you confirm the target, and will not advance through phases without the prior bundle uploaded.

Reporting issues

File against this repo with tag [archaeology-plugin]. Include:

  • the bundle filename (carries the version),
  • which phase you were running,
  • the engagement key,
  • the upload manifest the plugin echoed in its first response,
  • any failing assertion text from the Phase 4 VALIDATION-CHECKLIST.md.

This page as Markdown — for pasting into Claude or another assistant · llms.txt