unic / unic/unic-agents-plugins
Give /setup install provenance and a --check mode
Nobody has claimed this yet.
- 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
/setupinstalls 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 oneINSTALLED.mdnaming this plugin and the version that installed
the Bundle. NoSKILL.mdis stamped, and no upstream Method file is edited. -
/setup --checkwrites nothing and reports, per artefact class, whether the installed copy
matches the plugin on disk. -
--checktreats 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. -
--checkreports 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/setupwrites agree. -
--checkhas been run againstDXP-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 rootAGENTS.mddoes for a vendored Bundle
upgrade — is the cheapest honest answer, but it is not decided. - Whether
--checkbelongs on/setupor on/archon-upgrade./archon-upgradealready reads
versions and re-asserts the ADR-0011 schema traps by reading. The overlap is real and undecided.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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