Skills reach consuming repos as an npm dependency, never as copied bytes

Successor to neomjs/neo#17784 (CLOSED NOT_PLANNED). Graduated from D#17756 comment 18159875.

Context

neomjs/neo#17784 shipped a canonical store and then copied its bytes into every consuming repo, with a receipt and a two-leg guard to police divergence between those copies. The operator rejected that twice — SSOT violation on neomjs/devindex#6, and a merged-then-reverted neomjs/neo-agent-brain#5 — and @neo-gpt falsified its freshness model: a consumer pinned to an older canonical revision verified green while measurably behind. A store whose contents are duplicated N times is not canonical, and the machinery needed to police those duplicates was evidence of the mistake rather than mitigation of it.

The operator's mechanism, first-hand: "Other repos have an npm DEPENDENCY for the skills repo. postinstall hook can create SYMLINKS into the node_module[s]. Skill changes ⇒ package.json VERSION BUMP. This is KISS ⇒ TRIVIALLY EASY."

Live latest-open sweep: latest 20 open issues at 2026-08-26T09:11:07Z; no equivalent. Closed sweep run because this topic has a closed predecessor — only neomjs/neo#17784 itself. A2A: Emmy's lifecycle broadcast mandates a new successor; no peer claim outstanding.

The Problem

Nothing kept consuming repos current, and the failure mode was invisible staleness — neomjs/devindex carried a hand-copied AGENTS.md and no skill tree at all, with no instrument reporting either. That problem is real. The rejected fix was the transport, not the goal.

Committed copies fail for a structural reason worth stating once: they create N authoritative-looking trees, so every subsequent question ("is this repo current?") requires bespoke machinery to answer. An npm dependency answers it with npm outdated.

The Architectural Reality

• neomjs/neo-agent-skills — dev is the sole branch (operator-switched); main becomes release-only via the pipeline. Package contract already live at dev@ecb4e69a07: package.json (neo-agent-skills@0.1.0, unscoped per the neo.mjs / neo-agent-brain convention) and scripts/materialize-harness-skills.mjs.
• neomjs/neo — today authors .agents/skills and carries 37 committed .claude/skills links. Both change: authoring moves to canonical, and the links become untracked projection.
• npm install <pkg> does not run the consumer's postinstall; only a bare npm install does. Measured on a clean fixture. The command that bumps the dependency therefore leaves links stale until the next install.
• npm ci --ignore-scripts skips postinstall and prepare, and is already deliberate practice in three neomjs/neo workflows — under this transport it yields a resolved dependency and zero reachable skills.

The Fix

1. Publish neo-agent-skills to the registry. Currently E404; the npm org is operator-owned and no agent can clear it.
2. Consumers take the dependency — package.json entry plus lockfile — and run the materializer from postinstall.
3. Untrack the projection. .claude/skills becomes git-ignored; the 37 committed links are removed from neomjs/neo.
4. Authoring moves to neo-agent-skills/dev; promotion is version bump + publish.
5. Consumer CI asserts materialization, which is the whole answer to --ignore-scripts.

Contract Ledger Matrix

Decision Record

Required: ADR — ADR 0041 is Proposed with its transport and freshness sections rescinded; this ticket supplies the replacement text and flips it to Accepted.

Decision Record impact

amends ADR 0041 (transport + freshness) · aligned-with ADR 0040 — skill-tree custody after the cut stays the cut's question, not this ticket's.

Acceptance Criteria

• AC-1 — neo-agent-skills resolves from the registry; npm view neo-agent-skills version returns a version.
• AC-2 — neomjs/neo, neomjs/neo-agent-brain, and neomjs/devindex each declare the dependency and run the materializer from postinstall; a clean git clone + npm install yields a working projection with zero skill bytes tracked, proven by git ls-files. Widened 2026-08-26 by operator directive — the Brain must consume the substrate today, and this AC named only neomjs/neo. Brain consumption is purely additive (it never carried the corpus); neomjs/neo sheds 170 files.
• AC-3 — both projection surfaces are untracked in neomjs/neo and git-ignored: the 37 .claude/skills links and the 133-file .agents/skills tree. A tracked entry under either fails CI. Widened 2026-08-26 after @neo-gpt's audit added the harness-neutral .agents/skills surface: 0.1.1's guard refuses to materialize over git-tracked content, so leaving .agents/skills tracked makes the whole transport inert on this repo. Consequence stated plainly — neomjs/neo stops authoring the corpus and becomes a pure consumer, which is D#17782's stated model ("consume … at pinned revisions") but is a larger change than this AC originally described.
• AC-4 — consumer CI runs --check and goes red when materialization did not happen. Red control: an npm ci --ignore-scripts install must fail it, demonstrated, not asserted.
• AC-5 — no freshness gate, no epoch-lag check, no red-at-historical-pin exists anywhere in the mechanism. Absence is the criterion.
• AC-6 — rewrite ADR 0041 and flip it to Accepted. VOID: ADR 0041 exists only on closed, unmerged PR neomjs/neo#17793 and never entered dev; there is no repository document to amend or accept.

Out of Scope

• Skill-tree custody after the cut — neomjs/neo#17786's manifest decides it.
• Enforcement binding / required status checks — neomjs/neo#17783.
• The Windows core.symlinks arm and commit-vs-gitignore of link entries beyond AC-3.
• Re-litigating transport. The operator has ruled; submodule and committed-copy ideation is closed.

Avoided Traps

• Committed copies. Rejected twice by the operator; duplicated bytes are what made the drift machinery necessary.
• A bespoke freshness gate. Explicitly retracted upstream as manufactured-problem machinery. npm outdated is the surface.
• Assuming postinstall ran. Measured: npm install <pkg> does not fire it, and --ignore-scripts skips it. AC-4 is the arm, not an assumption.
• A git-URL dependency. Complicates lifecycle scripts; registry is the KISS reading.

Related

neomjs/neo#17784 (closed predecessor) · neomjs/neo#17783 (enforcement custody) · neomjs/neo#17791 (blocked on this) · neomjs/neo#17500 · D#17756 · D#17782 · ADR 0041

Origin Session ID: f27af939-3cec-4f52-a67d-e4e8786fed08

Retrieval Hint: query_raw_memories("npm transport skills dependency postinstall symlink ignore-scripts materialization")