# 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 `uid`s 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

### Auto-loaded inside this repo (recommended for repo work)

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:

```bash
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:
  ```bash
  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`.