canned-prompts/workplans/CANP-WP-0005-inclusion-diamond.md

---
id: CANP-WP-0005
type: workplan
title: "Document and detect inclusion diamonds"
domain: agents
repo: canned-prompts
status: proposed
owner: codex
topic_slug: practice
created: "2026-09-06"
updated: "2026-09-06"
---

# Document and detect inclusion diamonds

Residual from `CANP-WP-0004` (`origin: residual`, `origin_ref: CANP-WP-0004`).

## Warn about repeated inclusion

```task
id: CANP-WP-0005-T01
status: todo
priority: medium
```

CPF inclusion (§ 10.4) does not deduplicate: when one package reaches the same
dependency by two paths, the included text renders once per path. This was found
by building a real collection — `helix/repo-advance` rendered its conventions
block twice — and worked around downstream by factoring the shared routine into
its own fragment.

§ 10.4 says nothing about it, so an author meets the behaviour only by reading
the output carefully. That silence is the defect.

Two questions, and the second depends on the first:

1. **Document it.** State in § 10.4 that inclusion is textual and repeated,
   not deduplicated, and give the factoring pattern that avoids a diamond.
2. **Detect it.** Decide whether validation should warn when a package reaches
   the same dependency by more than one path. A warning is cheap and catches the
   mistake at `add` time. Silently deduplicating is a different proposition
   entirely — it would mean choosing which occurrence survives, and deciding what
   happens when two paths resolve *different versions* of the same dependency.
   That is resolver behaviour, and § 10.4 keeps composition declarative on
   purpose.

Leaning: document it now, warn at validation time, and do not deduplicate.
Add the catalog index, and package a real prompt collection CANP-WP-0004. The operator asked canned-prompts to build a database of versioned prompts recording where each came from and when — the first step toward a platform for collaborative prompting. The format had nowhere to put that. `provenance` records who wrote a prompt and where the idea came from; nothing recorded how a copy arrived in a particular store. Section 20.3 now specifies an `index.yaml` as store metadata rather than package data: how a copy arrived differs for every consumer, and recording an arrival must never rewrite the package that arrived. `add`, `install` and `publish` record registry, id, version, name, source, method, first-inclusion date, and the package's declared author, source and licence — the last three copied so a listing is readable without opening every package. A new `index` verb lists it. `included_at` is never overwritten; a re-run updates `last_seen_at`, because when a package first entered a collection is a fact about history rather than about the last command run. Tests 84 -> 90. Also records two findings from actually using the format: CANP-WP-0004-T03 — inclusion has no deduplication, so a diamond dependency renders shared content once per path. Found by composing a real collection. Not fixed here: deduplicating means choosing which occurrence survives and deciding what happens when two paths resolve different versions, which is resolver behaviour that section 10.4 deliberately avoids. Handed to CANP-WP-0005 with a leaning: document it, warn at validation time, do not deduplicate. The add_ons workaround in practice/pqrst-estimate is evidence about section 23's deferred "richer template syntax" — an optional appendix has to be an input with an empty default, because CPF has no conditionals. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bjefh8NUiEiahN4JLwoSKM Assistant: claude-code Assistant-Model: opus Assistant-Process: 388925@bnt-lap001 Assistant-Session: 3507023f-e0fd-4a1e-9d90-a0d4217d1502 2026-09-06 17:14:21 +02:00			`---`
			`id: CANP-WP-0005`
			`type: workplan`
			`title: "Document and detect inclusion diamonds"`
			`domain: agents`
			`repo: canned-prompts`
			`status: proposed`
			`owner: codex`
			`topic_slug: practice`
			`created: "2026-09-06"`
			`updated: "2026-09-06"`
			`---`

			`# Document and detect inclusion diamonds`

			Residual from `CANP-WP-0004` (`origin: residual`, `origin_ref: CANP-WP-0004`).

			`## Warn about repeated inclusion`

			```task
			`id: CANP-WP-0005-T01`
			`status: todo`
			`priority: medium`
			```

			`CPF inclusion (§ 10.4) does not deduplicate: when one package reaches the same`
			`dependency by two paths, the included text renders once per path. This was found`
			by building a real collection — `helix/repo-advance` rendered its conventions
			`block twice — and worked around downstream by factoring the shared routine into`
			`its own fragment.`

			`§ 10.4 says nothing about it, so an author meets the behaviour only by reading`
			`the output carefully. That silence is the defect.`

			`Two questions, and the second depends on the first:`

			`1. Document it. State in § 10.4 that inclusion is textual and repeated,`
			`not deduplicated, and give the factoring pattern that avoids a diamond.`
			`2. Detect it. Decide whether validation should warn when a package reaches`
			`the same dependency by more than one path. A warning is cheap and catches the`
			mistake at `add` time. Silently deduplicating is a different proposition
			`entirely — it would mean choosing which occurrence survives, and deciding what`
			`happens when two paths resolve different versions of the same dependency.`
			`That is resolver behaviour, and § 10.4 keeps composition declarative on`
			`purpose.`

			`Leaning: document it now, warn at validation time, and do not deduplicate.`