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 under db/engagements/<engagementKey>/ — leaf KnowledgeDomain Cypher, three-layer Context Artifacts, DecisionTraces with the full v1.3 schema, an eleven-dimension readiness verdict, a Site Package, and PromotionCandidate analysis.

  • Latest bundle: rosetta-archaeology-0.9.1.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 — repo/seed 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.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 under db/seeds/ (projectId='SYSTEM').
  • rosetta-archaeology authors engagement-scoped instances under db/engagements/<engagementKey>/ (projectId='<ENGAGEMENT-KEY>').

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.9.1.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.9.1.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.

No connector wiring is needed. The plugin runs entirely off uploaded files.

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 repo/seed inventory 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.

Applying the output to your checkout

Phase 4 emits a VALIDATION-CHECKLIST.md and a PARTNER-CERTIFICATION-REQUEST.md. Workflow:

cd ~/path/to/rosetta-platform
unzip -o ~/Downloads/rosetta-archaeology-<engagement>-phase4-*.zip
# Engagement Cypher lands at db/engagements/<engagementKey>/
# Site Package lands at site-packages/<partnerKey>/<engagementKey>/

Then follow the bundle's VALIDATION-CHECKLIST.md — including the note that make seed-compile may need to learn the db/engagements/ directory before deploy. The Make toolchain update is flagged for the operator, not done by the plugin.

After local validation, 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

Canonical content keeps its existing destinations per ADR-PA-002:

  • engagement Cypher 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): C-2 (Cypher canonical), C-4 (Make is the user surface), C-5 (five-field identity), C-6 (ProvenanceEvent on every mutation), C-7 (producer-only — never references rosetta-app-server).

It produces; you operate. The plugin never invokes make, cypher-shell, mysql, docker, or any command on your machine, 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.