unic / unic/unic-agents-plugins

Give /setup install provenance and a --check mode

Open
#408 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc needs-specs p2 tech-debt wayfinder:task
Dominant language
JavaScript
Stars
1
Forks
0
Avg merge
16h 43m
Merged PRs (30d)
19

Description

Question

Give /setup install provenance and a read-only --check mode, so a Consumer can see which plugin
version its installed artefacts came from and find out that a copy has gone stale.

Decided on #402 and recorded in the
Decisions-so-far passage on #373. The short
version: /setup is the Consumer's installer, autoUpdate goes off in a Consumer, and drift
therefore stops being an unattended overwrite and becomes staleness by inaction. Nothing detects
that today, and both real failures to date — #389's wrong parity claim, and the two rotted files the
0.23.0 port found — were detection failures.

This is the read half. #383 rewrites
setup.md and owns every write. This ticket owns what the writes record and what reads them back. It
is blocked by #383 for one concrete reason: /setup must locate the plugin's own installed directory
before it can compare anything against it, $CLAUDE_PLUGIN_ROOT is not set inside the Bash tool, and
ADR-0036's
2026-08-20 amendment assigns that mechanism to #383.

One reversal to record. ADR-0036's 2026-08-14 amendment states that the record file its
Consequences deferred to #295 is not built, and that per-file provenance is the whole mechanism.
.archon/methods/INSTALLED.md makes that sentence untrue for the directory entry. The rule that
replaces it: a named entry carries its own header, a directory entry carries one record — the
split CONTEXT.md § Install set already draws.

Acceptance criteria

  • Every Box YAML /setup installs carries the Generated header, and the header names this plugin,
    the plugin version that wrote the file, the Archon version observed at install time, and that the
    next run replaces the file.
  • .archon/methods/ carries one INSTALLED.md naming this plugin and the version that installed
    the Bundle. No SKILL.md is stamped, and no upstream Method file is edited.
  • /setup --check writes nothing and reports, per artefact class, whether the installed copy
    matches the plugin on disk.
  • --check treats the two tenant classes differently from the two plugin classes: for the config
    and the two tracker docs it reports presence and what differs, and never describes a replacement
    it would perform.
  • --check reports an artefact that carries no Generated header as unknown-provenance rather than
    as matching, because every artefact installed before this ticket is headerless.
  • ADR-0036 carries a fourth amendment naming which sentence of its 2026-08-14 amendment stopped
    being true, and why the directory entry now carries a record while the named entry does not.
  • CONTEXT.md § Generated header states the Archon-version line and the Methods record, so the
    vocabulary and what /setup writes agree.
  • --check has been run against DXP-DesignSystem, and its output is quoted on this ticket. Expect
    it to report all four Boxes as unknown-provenance: they were hand-copied at 0.23.0 and none carries
    a header.

Open questions this ticket must settle before it is dispatched

  • The report shape. "Names each difference" is not a format. A whole-file comparison, a first-line
    header comparison, and a line diff are three different answers, and an implementer will pick one and
    defend it. Decide it, or the criteria above have a gap.
  • Who remembers to run --check. The cure for "a hand-carried artefact nobody checks" is still a
    command a human must remember. Naming the moment — as the root AGENTS.md does for a vendored Bundle
    upgrade — is the cheapest honest answer, but it is not decided.
  • Whether --check belongs on /setup or on /archon-upgrade. /archon-upgrade already reads
    versions and re-asserts the ADR-0011 schema traps by reading. The overlap is real and undecided.

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 #383, ADR-0036, .archon/methods/INSTALLED.md, and CONTEXT.md sections Install set and Generated header. Resolve the open questions about report shape, invocation ownership, and when checks run before implementation. Done means the stated provenance, read-only reporting, ADR, documentation, and DXP-DesignSystem verification criteria are all addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.