|
| 1 | +# Evolution Report: Payload-Relative Reference Convention |
| 2 | +## Date: 2026-06-23 |
| 3 | + |
| 4 | +### Product Evolution |
| 5 | + |
| 6 | +#### Acceptance Criteria Results |
| 7 | + |
| 8 | +Cycle-level contract from SPEC.md, mapped to evidence. All pass — verified by grep battery + |
| 9 | +`trellis-check.sh` (11/11 skills, exit 0) + `run-tests.sh` (30/30). |
| 10 | + |
| 11 | +| Acceptance criterion (SPEC) | Evidence (slice / commit) | |
| 12 | +|---|---| |
| 13 | +| `grep references/STATE.md plugins/vine/skills/` returns zero; same for any `references/…` (#142) | Slice 2 — e72f448 (grep: 0 matches) | |
| 14 | +| No bare `agents/`, `skills/`, `hooks/` path in a skill body; cross-refs by name or `${CLAUDE_PLUGIN_ROOT}` (#138) | Slice 2 — e72f448 (grep: 0 matches) | |
| 15 | +| `references/STATE.md` gone; `references/CONTRACTS.md` present; no live file references `STATE.md`; CHANGELOG + dated ADRs period-accurate | Slice 0 — e75b744 (file moved; 5 CHANGELOG + 6 ADR refs preserved) | |
| 16 | +| `vine:init` README (step 4) + CLAUDE.md (step 8) write no `references/…` pointer (#141) | Slice 2 — e72f448 (grep: 0 in init/optimize) | |
| 17 | +| Convention documented in CLAUDE.md "Skill Authoring Conventions" + CONTRACTS.md "Reference Legibility" companion | Slice 1 — bc04aef (both homes present) | |
| 18 | +| Runtime-critical content inlined; a spot-run of one phase still produces a correct artifact | Slice 2 — e72f448 (PROFILE.md format inlined in verify+evolve; the live navigate session itself + this evolve run are the spot-run) | |
| 19 | +| `/trellis` fails on a deliberate `references/…` injection, passes on the corrected tree, does not trip on bucket-2 `.vine/context/…` | Slice 3 — 01db36c (Check 13; 3 CI-parity tests, both directions) | |
| 20 | + |
| 21 | +No **unaccounted** criteria. The three remaining `STATE.md` reference sites are all |
| 22 | +period-accurate by design: CHANGELOG (5), this feature's own CONTEXT/SPEC/NAVIGATION, and the |
| 23 | +dated `.vine/knowledge/workflow/` ADRs. |
| 24 | + |
| 25 | +#### Spec Deviations |
| 26 | + |
| 27 | +All three were navigate-annotated in SPEC.md addenda — justified, in-scope tactical extensions, |
| 28 | +none changing user-facing behavior beyond what the issues' ACs already required: |
| 29 | + |
| 30 | +| Deviation | Slice | Verdict | |
| 31 | +|---|---|---| |
| 32 | +| `optimize/SKILL.md` also wrote a dead `references/STATE.md` pointer into a consumer CLAUDE.md (spec named only init) | 2 | Justified — required by the zero-`references/` AC regardless; same #141 class as init | |
| 33 | +| Removed the navigate/evolve "verification-tier contract" pointer broke `/trellis` Check 10; removed the two stale anchor pairs from all three coupled homes | 2 | Justified — mechanical consequence of pointer removal; CONTRACTS + agent anchors (6 pairs) still resolve | |
| 34 | +| Three descriptive bare-payload-path prose mentions reworded (init `skills/<name>/SKILL.md`, init `hooks/hooks.json`, evolve "skills/commands"); plus a prose "skills/agents" despaced for the guard | 2, 3 | Justified — within the #138 no-bare-path AC; the prose `X/Y` despace is a known limitation of Check 13's non-slash-boundary heuristic, documented in the check prose | |
| 35 | + |
| 36 | +#### Follow-Up Items |
| 37 | + |
| 38 | +None new. The cycle closes #142, #141, #138 in full. Two pre-existing, already-tracked notes |
| 39 | +remain (not new work this cycle introduced): |
| 40 | +- Legacy `.vine/hooks/` fallback warnings in init harden to failures at 0.5 (tracked with the |
| 41 | + 0.4.0 release; warning-only by design today). |
| 42 | +- Version bump (patch vs minor) is a release-time call — see Handoff. A `[Unreleased]` CHANGELOG |
| 43 | + entry was staged this cycle. |
| 44 | + |
| 45 | +### Agent Evolution |
| 46 | + |
| 47 | +#### CLAUDE.md Suggestions |
| 48 | + |
| 49 | +None to draft — the convention itself was written into CLAUDE.md "Skill Authoring Conventions" |
| 50 | +during Slice 1 (bc04aef), with the rationale in CONTRACTS.md "Path resolution by audience." The |
| 51 | +agent-capability gain this cycle is already committed. |
| 52 | + |
| 53 | +#### Skill Suggestions |
| 54 | + |
| 55 | +None. No repeatable scaffold or workflow emerged — this was a one-time convention cleanup. |
| 56 | + |
| 57 | +#### VINE Process Observations |
| 58 | + |
| 59 | +- **Dogfooding meta-note**: this very evolve run executed from a *cached 0.4.0 plugin copy* whose |
| 60 | + body still cites `references/STATE.md` — the exact dead-pointer the feature fixes, surviving in |
| 61 | + the install cache until the next plugin refresh. A live demonstration of why the convention |
| 62 | + matters, and a reminder that contributor sessions should refresh the local plugin install after |
| 63 | + editing skills (the dev loop). Transient, no action needed. |
| 64 | +- The strictly-sequential 0→1→2→3 slicing held cleanly: rename first meant Slice 2 touched each |
| 65 | + citation once against the final name. The one recurring friction was Check 10's anchor coupling |
| 66 | + surfacing twice (Slice 0 forward, Slice 2 in reverse) — captured as durable knowledge below. |
| 67 | + |
| 68 | +#### Context Overlay Updates |
| 69 | + |
| 70 | +None. The Check 13 guard is already wired into `trellis-check.sh`, which the `## Validation` block |
| 71 | +in `shared.md` already points at — no overlay edit needed. |
| 72 | + |
| 73 | +### User Evolution |
| 74 | + |
| 75 | +#### Engineer Contributions |
| 76 | + |
| 77 | +- **The (a) vs (b) direction call** — choosing "shipped skills are self-contained / `references/` |
| 78 | + is contributor-doc" over "ship `references/` into the payload." This was the headline open |
| 79 | + question left deliberately open at verify; resolving it toward documentation-not-mechanism |
| 80 | + extended an established thread rather than reversing the just-shipped payload-scope decision. |
| 81 | +- **The STATE → CONTRACTS rename insight** — recognizing the file's name had outgrown its content |
| 82 | + ("state" was both too narrow and colliding with session state), folded into Slice 0 so later |
| 83 | + edits touched each citation once. |
| 84 | +- **The period-accurate historical carve-out** — insisting CHANGELOG and dated ADRs keep saying |
| 85 | + `STATE.md`. This is the same instinct applied before (issue freshness, knowledge immutability): |
| 86 | + historical records are period-accurate, not drift. |
| 87 | + |
| 88 | +#### Profile Updates |
| 89 | + |
| 90 | +No change. `workflow` stays `confident` — this cycle was convention-cleanup squarely in the |
| 91 | +engineer's wheelhouse (they drove the v0.4.0 payload-scope decisions this builds on). No growth |
| 92 | +log entry (engineer's call: skip). |
| 93 | + |
| 94 | +#### Claude Memory Suggestions |
| 95 | + |
| 96 | +None surfaced. No new general interaction preference emerged — the cycle ran free-climb, |
| 97 | +batch-by-size, consistent with existing recorded preferences. |
| 98 | + |
| 99 | +#### Durable Decisions Distilled |
| 100 | + |
| 101 | +One knowledge record written: `.vine/knowledge/workflow/2026-06-23-shipped-skills-are-self-contained-references-is-contributor-doc.md` |
| 102 | +— captures *why* direction (a) beat (b), the non-regenerable judgment CLAUDE.md's rule-text doesn't |
| 103 | +preserve. The guard's non-slash-boundary regex heuristic was considered and skipped (recoverable |
| 104 | +from the script + comments). |
| 105 | + |
| 106 | +### Handoff Package |
| 107 | + |
| 108 | +#### PR Description |
| 109 | + |
| 110 | +```markdown |
| 111 | +## Summary |
| 112 | +Shipped VINE skills cited `references/STATE.md` (~67×) and bare `agents/…` paths that don't |
| 113 | +exist where the code runs — a skill executes with the *consuming* repo as cwd, and `references/` |
| 114 | +isn't in the plugin payload. `vine:init` even wrote those dead pointers into other repos' README |
| 115 | +and CLAUDE.md. This establishes one convention — shipped skills are self-contained — and applies |
| 116 | +it everywhere, with a guard so it can't drift back. Closes #142, #141, #138. |
| 117 | + |
| 118 | +## Changes |
| 119 | +- **Rename** `references/STATE.md` → `references/CONTRACTS.md` (name now matches the content — |
| 120 | + artifact templates plus cross-cutting conventions, not just "state"). Live references updated; |
| 121 | + CHANGELOG and dated knowledge ADRs left period-accurate. (e75b744) |
| 122 | +- **Document** the three-bucket reference convention in CLAUDE.md and CONTRACTS.md. (bc04aef) |
| 123 | +- **Apply** it across 9 skills: ~60 dead `references/` pointers removed (runtime-critical content |
| 124 | + inlined), agent citations switched to invocable names, and init/optimize no longer write |
| 125 | + VINE-internal pointers into consumer repos. (e72f448) |
| 126 | +- **Guard** it: `/trellis` Check 13 fails on any shipped-surface VINE-internal reference. (01db36c) |
| 127 | + |
| 128 | +## Decisions Made |
| 129 | +- Direction: `references/` is contributor documentation, not a runtime contract — so it doesn't |
| 130 | + ship and the runtime is never told to read it. Honors the payload-scope and overlay-distribution |
| 131 | + decisions; no payload duplication. |
| 132 | +- Historical records (CHANGELOG, dated ADRs) keep naming `STATE.md` — period-accurate, not drift. |
| 133 | + |
| 134 | +## Testing |
| 135 | +- `grep -rn "references/" plugins/vine/skills/` → 0 matches; no bare `agents|skills|hooks/` paths. |
| 136 | +- `sh .vine/scripts/trellis-check.sh` → exit 0 (11/11 skills, Check 13 green). |
| 137 | +- `sh .vine/scripts/run-tests.sh` → 30/30 (includes 3 new Check 13 tests, both directions). |
| 138 | + |
| 139 | +## Follow-up |
| 140 | +None — the three issues are fully closed. Version bump (patch vs minor) is a release-time call; |
| 141 | +a `[Unreleased]` CHANGELOG entry is staged. |
| 142 | +``` |
| 143 | + |
| 144 | +#### Reviewer Notes |
| 145 | + |
| 146 | +- **The rename is the riskiest mechanical bit.** Check 10 in `/trellis` couples a skill's pointer |
| 147 | + phrase to an anchor pair living in three places (`trellis-check.sh`, `trellis.md`, |
| 148 | + `run-tests.sh`). The rename and the later pointer removals each had to update all three in |
| 149 | + lockstep; the green `trellis-check` + 30/30 tests confirm they did. |
| 150 | +- **Three navigate addenda go beyond SPEC's named scope** (optimize's consumer pointer, the |
| 151 | + removed Check 10 anchor pairs, the despaced prose `X/Y`). All are annotated in SPEC.md and |
| 152 | + required by the issues' ACs — not scope creep. |
| 153 | +- **Bucket-2 is legitimate.** The shipped `vine-verification` agent reads `.vine/context/shared.md` |
| 154 | + (the consumer's working tree) — that's a valid runtime path and Check 13 correctly leaves it |
| 155 | + alone. Don't "fix" it. |
| 156 | + |
| 157 | +#### Commit Suggestions |
| 158 | + |
| 159 | +Already committed as 4 slice commits (e75b744, bc04aef, e72f448, 01db36c) plus the navigate close |
| 160 | +(c3911f5). The evolve commit adds EVOLUTION.md, the knowledge ADR, the CHANGELOG entry, and the |
| 161 | +PROJECT-MAP update. |
| 162 | + |
| 163 | +#### Multi-PR Summary |
| 164 | + |
| 165 | +Not applicable — single PR, no Milestones table. All four slices ship together (tightly coupled; |
| 166 | +shipping separately would risk the divergent partial fixes CONTEXT warned against). |
0 commit comments