unic-archon-dlc: ADR links in commands/*.md resolve against the Consumer's repository

Version: measured on develop at 579b4ef4 (Plugin 0.31.0)

Problem

The Plugin's commands and Boxes refer to the Plugin's own ADRs, its README.md and this repository's issues. A Consumer session cannot follow any of them.

A command runs from the Plugin cache, but the agent resolves a relative link such as [ADR-0020](docs/adr/0020-specs-branch-on-input.md) from the Consumer's working directory. That finds nothing, or the Consumer's own ADR with the same number.
/setup copies the Box YAMLs into the Consumer's .archon/workflows/. They cite Plugin ADRs by number, such as (ADR-0023 §5), in comments and inside prompt text. In a Consumer whose own docs/adr/ reaches that number, the citation names the Consumer's decision. One measured Consumer has ADRs 0001 to 0010.
/setup writes an absolute URL to this repository into the Consumer's CLAUDE.md.

specs.md:27 forbids $CLAUDE_PLUGIN_ROOT, which is unset inside the Bash tool (#422), so a command cannot reach the Plugin root that way. /setup alone resolves the installed Plugin, through installPath in the plugin registry.

#301 found the command links and was closed as not planned.

Rulings

2026-09-24: shipped prose carries its content inline or does not carry it. It carries no link back to this repository, relative or absolute.
2026-10-27, in the grilling session:
1. A bare citation by number, such as ADR-0023 §5, is a reference back, in prompt text and in YAML comments alike.
2. /setup reads <installPath>/README.md for the README content it depends on (option B).
3. Only /setup reads from the installed Plugin. Every other command drops its ADR links and states inline any rule it needs.
4. Scope is what a Consumer session reads. The table below lists it.
5. The Plugin README.md keeps its links into its own docs/adr/. They resolve inside the installed Plugin.
6. A sentence in the Plugin's AGENTS.md is the whole guard. Nothing checks the rule mechanically.
7. The ticket that #631 will produce for commands/specs.md is blocked by this one.
8. The Plugin README.md's bare citations become links into its own docs/adr/, so they fall under ruling 5.
9. The line that the Box edits are unproven until a Consumer run reads them is a dispatch note, not a criterion.

Scope

In scope, measured on develop at 579b4ef4:

What	Where	Count
Relative links to a Plugin ADR, `docs/adr/` form	`archon-upgrade.md` 10, `cleanup.md` 12, `improve-architecture.md` 11, `specs.md` 10, `tickets.md` 10, `triage.md` 12	65
Relative links to a Plugin ADR, `../docs/adr/` form	`setup.md`	10
Relative links to the Plugin `README.md`	`setup.md`	6
Links to issues in this repository	`specs.md` 2, `setup.md` 1	3
An absolute URL to the Plugin `README.md`, written by `/setup` into the Consumer's `CLAUDE.md` ("What each box does")	`setup.md`	1
The ADR-home rule, which names this repository's layout (`apps/claude-code/<plugin>/docs/adr/`, "monorepo-wide")	`improve-architecture.md`	1 rule
A path in this repository: "The Box command docs live at `docs/boxes/` in this Plugin's own repository"	`setup.md`	1
Bare citations of a Plugin ADR, to become links into the Plugin's `docs/adr/`	`README.md`	27
Citations of a Plugin ADR by number (`ADR-NNNN`), in comments and in prompt text	`unic-dlc-build.yaml` 32, `unic-dlc-explore.yaml` 21, `unic-dlc-pr-review.yaml` 21, `unic-dlc-qa.yaml` 18	92

Count the links with a pattern that matches both forms, such as grep -oE '\]\((\.\./)?docs/adr/'. A search for ](docs/adr/ alone misses the ten in setup.md. Count citations with grep -oE 'ADR-?0[0-9]{3}', not by matching lines.

In scope, with links into the Plugin kept: the Plugin README.md (its links into its own docs/adr/, 18 ADR-NNNN link labels on 14 lines) and vendor/mattpocock-skills/README.md (one link to ../../README.md). The README holds 45 ADR-NNNN matches: 18 are link labels and stay, and 27 are bare and become links.

Out of scope:

vendor/mattpocock-skills/skills/: upstream text, never hand-edited. Its one citation, "contradicts ADR-0007", is an invented example, not a Plugin ADR.
AGENTS.md, CHANGELOG.md, CONTEXT.md and docs/: read by this repository's developers, not by a Consumer session.
The homepage and repository fields of plugin.json and marketplace.json: read by the installer, not followed by an agent.
Files a Consumer wrote by hand, such as a header comment in its own .archon/unic-dlc.config.yaml.

Acceptance criteria

Amended 2026-10-27, approved by the maintainer in the grilling session. This replaces the criteria of 2026-09-24.

No in-scope file links to this repository, names a path in it, or cites a Plugin ADR by number. That covers its ADRs, its README.md, its other docs and its issues, in Markdown, in YAML comments and in prompt text, and it includes any text /setup writes into a Consumer file. The one exception: a relative link in the Plugin README.md or in vendor/mattpocock-skills/README.md that resolves inside the installed Plugin stays, label included (for example [ADR-0016](docs/adr/…)), because those files are read from <installPath>, where the link resolves. A bare ADR-NNNN citation in the Plugin README.md becomes such a link.
Where a command or a Box depends on content that exists only in the cited ADR, it states that content inline. A reference that served only a human reader, such as a "Design rationale" line or a parenthetical citation, is removed and not replaced.
/setup reads the README content it depends on, namely § Dependencies, § Configuration reference and § The tracker contract, from <installPath>/README.md, using the installPath it already resolves and verifies. A path a command resolves against the installed Plugin through installPath is inside the Plugin, not a link to this repository.
In the block /setup writes into the Consumer's CLAUDE.md, the "What each box does" URL is replaced by one line per Box that says what the Box does. The sentence in setup.md that describes what the block carries no longer says it carries a link.
/improve-architecture picks the ADR home from the Consumer's own tree. It offers the docs/adr/ directories the Consumer already has and confirms the choice with the user. If the Consumer has none, it proposes the root docs/adr/, which /specs already reads. It names no path from this repository's layout.
The steps that tell the agent to read the Consumer's own docs/adr/ keep their meaning: in /specs, and in the unic-dlc-explore.yaml and unic-dlc-build.yaml prompts. Removing citations does not remove those steps.
The Plugin's AGENTS.md states the rule in the first criterion and names all three forms: a link, a path and a citation by number. This sentence is the whole guard. Accepted gap: nothing checks the rule mechanically, so a diff that adds a reference merges green unless a reviewer reads it.
The Plugin's CHANGELOG.md carries the change under ## [Unreleased].

Dispatch notes

Start after #652 and #439 merge, from that develop. Native blocked_by edges to both enforce this. Both edit unic-dlc-qa.yaml and unic-dlc-build.yaml, plus the Plugin's CHANGELOG.md and plugin.json. One worker per file.
Re-measure every count in the scope table on that develop before editing. Both merges add text to unic-dlc-qa.yaml and unic-dlc-build.yaml.
The Box edits are unproven in a Consumer until a Consumer run reads them. A run in this repository does not prove them.
Prompt-text edits add no node, so no Archify diagram needs re-exporting.
The ticket that #631 will produce for commands/specs.md takes a blocked_by edge to this ticket when it is created.
Existing Consumers lose the absolute URL on their next /setup run, because /setup replaces its CLAUDE.md block in place.

Maintainer ruling, 2026-09-24: shipped prose links to nothing in this repository

The maintainer gave this ruling first-hand to the DLC orchestrator seat.

Neither the commands nor the Methods should carry any link to docs in this repository, because that material reaches the Consumer. Prose has no dependency manager like npm. So either it goes inside, or it goes out.

That rejects the fix proposed above. A URL pinned to a release tag still points outside the Consumer. It also has two defects of its own:

Nothing moves the pin. bump-version.mjs rewrites no URLs, so after the next release every pinned link names an older tag. Where an ADR was amended later, the agent reads the old text beside the new rule.
A link to a new ADR is dead when it is written. The commit comes before the bump, so it can name only the previous tag, where the ADR does not exist yet, or the next tag, which does not exist yet.

It also rejects pinning to main and the inline-only-where-a-rule-sits variant. Both keep a link out.

Scope, measured on `develop` at `8765f29`

What	Where	Count
Relative links to a Plugin ADR	six of the seven commands	65
Relative links to the Plugin `README.md`	`setup.md`	6
Links to issues in this repository	`specs.md`	2
An absolute URL to the Plugin `README.md` that `/setup` writes into the Consumer's own file, in the "What each box does" line of its managed block	`setup.md`	1
The Methods bundle, the Box YAMLs, `.archon/commands/`	—	0

The ticket says the problem is in commands/, and that is correct. The Methods carry no such link. The docs/adr/ paths in unic-dlc-build.yaml and unic-dlc-explore.yaml point at the Consumer's own ADRs on purpose, and they stay.

Proposed criteria, pending the maintainer's approval

No file this Plugin ships to a Consumer links to, or names a path in, this repository: its ADRs, its README.md, its other docs or its issues. That covers the commands and any text /setup writes into a Consumer file.
Where a command depends on content that exists only in a linked document, the command states that content inline. A link that served only a human reader, such as a "Design rationale" line, is removed.
The steps that tell the agent to read the Consumer's own docs/adr/ are unchanged.
The Plugin's AGENTS.md states the rule, so that the next command written does not add a link back.
The Plugin's CHANGELOG.md carries the entry under ## [Unreleased].

The questions this does not decide yet are on this seat's side, with the maintainer.

Posted by unic-sdlc-orchestrator-3, the DLC seat.

Back to grilling: one open decision before dispatch

The maintainer wants a dedicated grilling session on this ticket before it is dispatched. The criteria in the body stay as the starting point. Nothing is dispatched.

The open question: how does /setup reach the Plugin README.md content it depends on? Two of its steps depend on README content, and neither link is decorative. The § Configuration reference is called "the single source of truth for every default". The § tracker contract step says "Read it and follow it … this step does not repeat them".

Option	Before	After	Cost
A. Inline	`setup.md` links `../README.md`	`setup.md` carries the configuration reference and the tracker contract itself	a copy of the README inside `setup.md`, and the two drift
B. Read from the installed Plugin	`setup.md` links `../README.md`	`/setup` reads `<installPath>/README.md`. Step 1 already resolves `installPath` from the plugin registry, and verifies `vendor/` and `.archon/workflows/` there	none new. The README ships inside the installed Plugin, so it is not a link to this repository

The maintainer leans towards B but has not yet read the point in setup.md where it resolves installPath. If B is chosen, the first criterion gains one sentence: a path that a command resolves against the installed Plugin through installPath is inside, not a link.

The grilling should also settle whether B stays limited to /setup, the only command that resolves installPath. The other commands use their ADR links as rationale, and those are removed.

Stale — do not follow. The grilling this opener started is closed. The current opener is #556 (comment).

Opener — How to start this session (written 2026-10-27 by unic-sdlc-orchestrator-7, at dispatch)

What this session produces

Approved acceptance criteria in this ticket's body, then the label ready-for-agent. Nothing else. The fix runs later under /afk-loop 373.

This ticket's parent is #373, not #498. Start: the maintainer types /wayfinder 373 #556. When the grilling starts, the maintainer types /grill-with-docs. Both carry disable-model-invocation, so the session cannot invoke them itself.

Do not close this ticket. This overrides /wayfinder step 4. This stream grills a ticket into its own criteria and implements it under the same number. Do not invoke /implement, /tdd or /to-tickets. Keep needs-specs until the maintainer approves, then replace it with ready-for-agent.

Read in this order

This ticket's body. The criteria approved on 2026-09-24 are the starting point.
The ruling of 2026-09-24: shipped prose carries no link to this repository, relative or absolute.
The open decision in the second comment, "Back to grilling": option A (inline the README content in setup.md) or option B (/setup reads <installPath>/README.md). The maintainer leaned towards B but had not read the step yet.
apps/claude-code/unic-archon-dlc/commands/setup.md on origin/develop, the step that resolves installPath from the plugin registry (around line 70). Read it before the maintainer chooses A or B, because that step is the whole case for B.

The trap that costs an hour

Grilling against the scope table in the body. It was measured on 8765f29 on 2026-09-24, and the commands have moved since. Re-measured on 579b4ef4 on 2026-10-27: 75 relative ADR links across all seven commands, not 65 across six. setup.md now has some, written ../docs/adr/…, which the body's ](docs/adr/ count misses. Before any question, re-measure on origin/develop with a pattern that matches both forms, and correct the table. A criterion written against the old table leaves the new links in place, and every criterion still reads satisfied.

What this ticket does not decide yet

Each of these is a question for the maintainer. None is yours to settle with a plausible default.

A or B for /setup's README content. If B: the first criterion gains one sentence saying that a path a command resolves against the installed Plugin through installPath is inside the Plugin, not a link.
Whether B reaches beyond /setup. Only /setup resolves installPath today. The other commands' ADR links are rationale and are removed. Decide whether any of them is a rule a command needs inline, which the second criterion covers, or whether all of them go.
The Plugin README.md and the vendored Method bundle. README.md links docs/adr/ itself, and vendor/mattpocock-skills/README.md links ../README. Both ship inside the Plugin. Under B, a link inside the installed Plugin may be acceptable. The vendored bundle may not be hand-edited: upgrading it means diffing against upstream (root CLAUDE.md, the quality bar for a prose Box). Decide whether either is in scope, and say so in the criteria.
How the rule stays true. The sixth criterion puts it in the Plugin's AGENTS.md. The repository's quality bar rules out a test module written only to check prose. Decide whether a sentence in AGENTS.md is the whole guard, and write that down as the accepted gap.

Other traps

This repository is public, and its issues are too. Name no client, no Consumer repository, no city, sector or product. Write "the Consumer". The NDA hook refuses listed terms, and it does not catch a paraphrase.
/afk-loop 498 runs tonight on #652 and #439. It does not take this ticket, because this ticket hangs off wayfinder: unic-archon-dlc is prose, and proven at a Consumer #373. Both runs would edit the Plugin's CHANGELOG.md and plugin.json, so /afk-loop 373 starts after /afk-loop 498 stops, never alongside it.
#631's coming commands/specs.md ticket waits on this one. Ask whether that edge should exist before the label goes on.
Ask one question at a time while the answers still branch. Links, never bare ids, in everything you write on the tracker.

The bar that proves it

Run the four reads from docs/agents/dispatching-and-learning.md § Before you post one on the criteria as a set. Then check:

On the merged tree, a search of every file the Plugin ships finds no link and no path to this repository, in either the docs/adr/ or the ../docs/adr/ form, except what the criteria explicitly allow.
/setup still reaches its configuration defaults and its tracker contract steps, from content inline or from the installed Plugin.
No criterion offers two acceptable outcomes.

A false pass is a clean grep '](docs/adr/' with the ../docs/adr/ links still there.

On landing

Rewrite this ticket's body with the approved criteria and the corrected scope table, and post a comment saying what changed.
Before you apply any label, report to unic-sdlc-orchestrator-7 with the link. The orchestrator reads the criteria as one set and replies.
Then replace needs-specs with ready-for-agent, keep p0 unless the maintainer moves it, and leave it unassigned for /afk-loop 373.
Change no file in the repository.

Report back

BEFORE YOU FINISH, AND WHENEVER YOU LEARN SOMETHING THAT WOULD HAVE CHANGED THIS PROMPT,
report to unic-sdlc-orchestrator-7 with four things and nothing else:
  1. what you expected
  2. what happened
  3. the command or file that proved it
  4. whether it changes only this ticket, or every session in this repo
Send it when you learn it, not only at the end — a session that dies unreported
takes its learnings with it.
Talk only to unic-sdlc-orchestrator-7. Do not message another orchestrator or its
sessions; tell unic-sdlc-orchestrator-7, who relays it.

Review and handover

There is no pull request. The maintainer approves the criteria in the session. The orchestrator reads them as one set before the label goes on. Implementation runs under /afk-loop 373, which this seat records as unproven in the Consumer until a Consumer run reads it.

Grilling closed, 2026-10-27: criteria rewritten

The maintainer approved the criteria now in the body. What changed against the body of 2026-09-24:

Scope re-measured on develop at 579b4ef4. There are 75 ADR links, not 65, because setup.md now has ten in the ../docs/adr/ form, which a ](docs/adr/ search misses. There are 3 issue links, not 2: setup.md also links #647.
The Box YAMLs come back in. /setup copies them into the Consumer, and they cite Plugin ADRs by number 92 times, in comments and in prompt text. The old line "This ticket edits no Box file" is gone.
A citation by number counts as a reference, in comments too.
Option B: /setup reads <installPath>/README.md. No other command reads from the installed Plugin; their ADR links are removed, and any rule they need is stated inline.
Scope is a closed list of what a Consumer session reads. AGENTS.md, CHANGELOG.md, CONTEXT.md, docs/, the manifest metadata fields and the upstream Method text are out, and the body says why.
The Plugin README.md keeps its links into its own docs/adr/, because they resolve inside the installed Plugin.
The guard is one sentence in AGENTS.md, naming all three forms. The criterion records the gap: nothing checks the rule mechanically.
Dispatch notes added: start after #652 and #439 merge, and give the #631 ticket for commands/specs.md a blocked_by edge to this one.
The Box edits are unproven until a Consumer run reads them.

Labels stay as they are until the orchestrator has read the criteria as one set.

fix(unic-archon-dlc): drop issue and planning-doc numbers a Consumer …

fix(unic-archon-dlc): state the gate conditions and check every READM…

docs(unic-archon-dlc): correct three Box comments and the AGENTS.md g…

docs(unic-archon-dlc): match the Step 3 ADR-format sentence to the ho…

docs(unic-archon-dlc): drop repository paths from the bundle README

fix(unic-archon-dlc): describe the Box list and every gate in the CLA…

docs(unic-archon-dlc): replace planning labels and empty asides in co…

docs(unic-archon-dlc): drop the last amend-an-ADR step from /archon-u…

docs(unic-archon-dlc): tighten the last review findings in commands, …

Navigation Menu

Repository navigation

unic-archon-dlc: ADR links in commands/*.md resolve against the Consumer's repository #556

Problem

Rulings

Scope

Acceptance criteria

Dispatch notes

Related

Maintainer ruling, 2026-09-24: shipped prose links to nothing in this repository

Scope, measured on `develop` at `8765f29`

Proposed criteria, pending the maintainer's approval

Back to grilling: one open decision before dispatch

What this session produces

Read in this order

The trap that costs an hour

What this ticket does not decide yet

Other traps

The bar that proves it

On landing

Report back

Review and handover

Grilling closed, 2026-10-27: criteria rewritten

13 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

unic-archon-dlc: ADR links in commands/*.md resolve against the Consumer's repository #556

Description

Problem

Rulings

Scope

Acceptance criteria

Dispatch notes

Related

Activity

orioltf commented on Sep 24, 2026

Maintainer ruling, 2026-09-24: shipped prose links to nothing in this repository

Scope, measured on develop at 8765f29

Proposed criteria, pending the maintainer's approval

orioltf commented on Sep 24, 2026

Back to grilling: one open decision before dispatch

orioltf commented on Oct 27, 2026

What this session produces

Read in this order

The trap that costs an hour

What this ticket does not decide yet

Other traps

The bar that proves it

On landing

Report back

Review and handover

orioltf commented on Oct 27, 2026

Grilling closed, 2026-10-27: criteria rewritten

13 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Scope, measured on `develop` at `8765f29`