@deftai/directive-content 0.55.0

package/conventions/content-manifest.json

@@ -0,0 +1,399 @@
+{
+  "version": 2,
+  "description": "Content Manifest (#1821 / #1875): structural source of truth classifying repository entries into one of four buckets and enforcing the post-move LOCATION INVARIANT. Since #1875 every shippable `content` entry physically lives under the `content/` root (which the C1 flatten deposits to `.deft/core/<x>`), with the three named harness-entry files (AGENTS.md / main.md / SKILL.md) the only content-classified exceptions that remain at the repo root (`harnessEntry: true`). The deterministic gate `task verify:content-manifest` (packages/core/src/verify-source/content-manifest.ts, exposed via `deft-ts verify-content-manifest`) fails CI when a `content` entry is not under `content/`, when a non-`content` entry lives under `content/`, when a git-tracked `content/` child has no manifest entry (or a manifest content child is stale), when a bucket value is invalid, or when a path is listed twice. Refs #1821 (manifest v1 + gate), #1669 (epic / Wave-1 LockedDecisions D2/C1/C2/C3/C4), #1875 (content/ move).",
+  "buckets": [
+    {
+      "id": "content",
+      "label": "Content",
+      "description": "Framework knowledge/guidance/assets that a consumer consumes. Since #1875 these live under the `content/` root and deposit (C1 flatten) into the consumer's `.deft/core/`: standards docs, skills, templates, packs, conventions prose, core/framework docs, and deposited scaffolds. The three named harness-entry files (AGENTS.md / main.md / SKILL.md) are content-classified but root-resident (`harnessEntry: true`)."
+    },
+    {
+      "id": "engine",
+      "label": "Engine",
+      "description": "Executable framework runtime -- the code that enforces and runs deft. In the #1669 model this ships as the CLI package (npm/pip), not as editable deposited content: the TS packages, the Go installer, the Python scripts, the Taskfile + task fragments, the `run` CLI launchers, and the deposited git hooks."
+    },
+    {
+      "id": "harness",
+      "label": "Harness",
+      "description": "Build / test / language toolchain configuration required to build and test the engine inside THIS repo. Not shipped as-is; needed to produce the engine + content artifacts: package/lockfiles, compiler/linter/test config, and the framework's own test suite."
+    },
+    {
+      "id": "repo-dev",
+      "label": "Repo-dev",
+      "description": "Maintainer-only / repository artifacts that are neither shippable content nor engine runtime: CI config, git plumbing, planning docs, history/incident records, the maintainer's own vBRIEF lifecycle, framework spec fixtures, and the deft project's own product/release docs."
+    }
+  ],
+  "straddlePolicy": "C3 straddle policy (#1669 Wave-1 LockedDecisions): straddles are now PHYSICALLY RESOLVED by the #1875 content/ move -- the directories that previously straddled (vbrief/, meta/, incidents/, docs/, core/) were split so the shippable half lives under content/ and the maintainer-only half stays at the repo root. The remaining `straddle: true` markers (LICENSE.md, content/conventions) flag entries whose directory still carries a minority of differently-purposed files that travel together by necessity (e.g. content/conventions co-locates engine-consumed gate JSON with conventions prose). The gate enforces the location invariant over content/ children; it does not descend further into directories.",
+  "entries": [
+    {
+      "path": "content/.agents",
+      "bucket": "content",
+      "note": "Dogfood deposit of the deft skills (.agents/skills/) the deft repo's own agents load; consumer .agents/ is generated by the installer from embedded pointers, not copied from here."
+    },
+    {
+      "path": "content/LICENSE.md",
+      "bucket": "content",
+      "note": "Travels with the deposited payload; the engine CLI package also bundles its own copy at publish time.",
+      "straddle": true
+    },
+    {
+      "path": "content/QUICK-START.md",
+      "bucket": "content",
+      "note": "Consumer-facing onboarding doc; the AGENTS.md managed-section points consumers at .deft/core/QUICK-START.md for idempotent refresh."
+    },
+    {
+      "path": "content/UPGRADING.md",
+      "bucket": "content",
+      "note": "Consumer-facing upgrade guide cited by the doctor and install surfaces."
+    },
+    {
+      "path": "content/coding",
+      "bucket": "content",
+      "note": "Coding standards docs (coding.md, hygiene.md, testing.md, build-output.md, toolchain.md)."
+    },
+    {
+      "path": "content/commands.md",
+      "bucket": "content",
+      "note": "Framework commands reference doc."
+    },
+    {
+      "path": "content/context",
+      "bucket": "content",
+      "note": "Context-engineering standards docs."
+    },
+    {
+      "path": "content/contracts",
+      "bucket": "content",
+      "note": "Framework contract docs (boundary-maps, deterministic-questions, hierarchy)."
+    },
+    {
+      "path": "content/conventions",
+      "bucket": "content",
+      "note": "Conventions prose docs ship as content; co-located structured data files (rule-ownership.json, content-manifest.json) are engine-consumed gate inputs that travel with the same directory.",
+      "straddle": true
+    },
+    {
+      "path": "content/deployments",
+      "bucket": "content",
+      "note": "Per-platform deployment guidance docs (aws, azure, gcp, fly-io, cloudflare, ...)."
+    },
+    {
+      "path": "content/docs",
+      "bucket": "content",
+      "note": "Consumer-facing concept/guide docs promoted from the maintainer docs/ tree (BROWNFIELD.md, getting-started.md, good-agents-md.md) per #1669 Wave-1 C3."
+    },
+    {
+      "path": "content/events",
+      "bucket": "content",
+      "note": "Event-driven framework docs and JSON schemas (event-record.schema.json, registry.schema.json)."
+    },
+    {
+      "path": "content/glossary.md",
+      "bucket": "content",
+      "note": "Canonical framework glossary -- the former core/glossary.md merged with the unique vBRIEF-lifecycle terms from the former top-level glossary.md (#1875 dedup)."
+    },
+    {
+      "path": "content/incidents",
+      "bucket": "content",
+      "note": "Incident postmortem convention scaffold (_template.md + README.md); specific incident records stay at the maintainer-only root incidents/."
+    },
+    {
+      "path": "content/interfaces",
+      "bucket": "content",
+      "note": "Interface-design standards docs (cli, rest, tui, web)."
+    },
+    {
+      "path": "content/languages",
+      "bucket": "content",
+      "note": "Per-language standards docs (python, go, typescript, rust, ...)."
+    },
+    {
+      "path": "content/meta",
+      "bucket": "content",
+      "note": "Meta docs that ship: SOUL.md / code-field.md / morals.md / philosophy.md / security.md plus the former core/ docs (project.md, ralph.md, versioning.md). Repo-dev meta (ideas/suggestions/lessons/policy-changes.log) stays at root meta/."
+    },
+    {
+      "path": "content/packs",
+      "bucket": "content",
+      "note": "Versioned content packs (lessons, etc.) loaded via the packs:slice surface."
+    },
+    {
+      "path": "content/patterns",
+      "bucket": "content",
+      "note": "Pattern docs (goal-gate-determinism, build-model-ahead, generator-verifier-loop, ...)."
+    },
+    {
+      "path": "content/platforms",
+      "bucket": "content",
+      "note": "Platform-specific guidance docs (unity, 2600, ...)."
+    },
+    {
+      "path": "content/references",
+      "bucket": "content",
+      "note": "Reference docs (cost-models, ip-risk, plain-english-ux, ...)."
+    },
+    {
+      "path": "content/resilience",
+      "bucket": "content",
+      "note": "Resilience/session-continuity standards docs (continue-here.md, ...)."
+    },
+    {
+      "path": "content/scm",
+      "bucket": "content",
+      "note": "Source-control standards docs (git.md, github.md)."
+    },
+    {
+      "path": "content/secrets",
+      "bucket": "content",
+      "note": "Deposited secrets-handling scaffold directory (.gitkeep placeholder)."
+    },
+    {
+      "path": "content/skills",
+      "bucket": "content",
+      "note": "The deft skill library (deft-directive-*); the primary shipped guidance surface."
+    },
+    {
+      "path": "content/strategies",
+      "bucket": "content",
+      "note": "Strategy docs (delegate, interview, ...)."
+    },
+    {
+      "path": "content/swarm",
+      "bucket": "content",
+      "note": "Swarm orchestration standards docs (the swarm runtime lives in packages/ + tasks/swarm.yml)."
+    },
+    {
+      "path": "content/templates",
+      "bucket": "content",
+      "note": "Framework templates (agents-entry.md, agent-prompt-preamble.md, ...)."
+    },
+    {
+      "path": "content/tools",
+      "bucket": "content",
+      "note": "Tooling standards docs (taskfile.md, ...)."
+    },
+    {
+      "path": "content/vbrief",
+      "bucket": "content",
+      "note": "Shipped vBRIEF surface: schemas/, vbrief.md. The lifecycle folders + PROJECT-DEFINITION live at the maintainer-only root vbrief/. The framework's own migration RESULT artifacts (LEGACY-REPORT.md / RECONCILIATION.md / safety-manifest.json) are repo-dev and live at root vbrief/migration/ -- they are this repo's migration output, not a consumer convention, so they are not shipped (refines C3: migration/ held only framework-result records, not migration conventions)."
+    },
+    {
+      "path": "content/verification",
+      "bucket": "content",
+      "note": "Verification standards docs (stub detection, legacy-code detection)."
+    },
+    {
+      "path": "AGENTS.md",
+      "bucket": "content",
+      "harnessEntry": true,
+      "note": "Installer-managed framework guidance entry; the managed-section is rendered from content/templates/agents-entry.md and deposited to consumers. Harness-entry: stays at the repo root, not under content/ (#1669 D2)."
+    },
+    {
+      "path": "main.md",
+      "bucket": "content",
+      "harnessEntry": true,
+      "note": "The full framework guidelines -- the canonical entry doc consumers read. Harness-entry: stays at the repo root, not under content/ (#1669 D2)."
+    },
+    {
+      "path": "SKILL.md",
+      "bucket": "content",
+      "harnessEntry": true,
+      "note": "Top-level deft skill entry (the `deft` skill); part of the shipped skills surface. Harness-entry: stays at the repo root, not under content/ (#1669 D2)."
+    },
+    {
+      "path": ".githooks",
+      "bucket": "engine",
+      "note": "Deposited pre-commit/pre-push hooks (#1463) that invoke the gate scripts -- executable enforcement installed by `task setup` / the installer."
+    },
+    {
+      "path": "cmd",
+      "bucket": "engine",
+      "note": "Go installer (cmd/deft-install) -- the canonical bootstrap/upgrade binary."
+    },
+    {
+      "path": "packages",
+      "bucket": "engine",
+      "note": "TypeScript engine monorepo (@deftai/cli, @deftai/core, @deftai/types) -- the gate + lifecycle runtime."
+    },
+    {
+      "path": "run",
+      "bucket": "engine",
+      "note": "POSIX `run` CLI launcher shim."
+    },
+    {
+      "path": "run.bat",
+      "bucket": "engine",
+      "note": "Windows `run` CLI launcher shim."
+    },
+    {
+      "path": "run.py",
+      "bucket": "engine",
+      "note": "Python `run` CLI entrypoint dispatched by the run shims."
+    },
+    {
+      "path": "scripts",
+      "bucket": "engine",
+      "note": "Python engine scripts (gate oracles, lifecycle, triage, release) invoked by the Taskfile and TS dispatcher."
+    },
+    {
+      "path": "tasks",
+      "bucket": "engine",
+      "note": "Taskfile fragments (verify, scope, triage, pr, ...) that orchestrate the engine verbs."
+    },
+    {
+      "path": "Taskfile.yml",
+      "bucket": "engine",
+      "note": "Root task runner manifest that orchestrates the engine gates and lifecycle verbs."
+    },
+    {
+      "path": ".nvmrc",
+      "bucket": "harness",
+      "note": "Node version pin used to build the TS engine."
+    },
+    {
+      "path": "biome.json",
+      "bucket": "harness",
+      "note": "Biome formatter/linter config for the TS engine."
+    },
+    {
+      "path": "go.mod",
+      "bucket": "harness",
+      "note": "Go module definition for the installer build."
+    },
+    {
+      "path": "package.json",
+      "bucket": "harness",
+      "note": "Root pnpm workspace manifest for the TS engine build/test."
+    },
+    {
+      "path": "pnpm-lock.yaml",
+      "bucket": "harness",
+      "note": "pnpm dependency lockfile for the TS engine."
+    },
+    {
+      "path": "pnpm-workspace.yaml",
+      "bucket": "harness",
+      "note": "pnpm workspace package globs for the TS engine."
+    },
+    {
+      "path": "pyproject.toml",
+      "bucket": "harness",
+      "note": "Python project + pytest/ruff/mypy config for the Python engine scripts and their tests."
+    },
+    {
+      "path": "tests",
+      "bucket": "harness",
+      "note": "The framework's own test suite (Python); pruned from the consumer deposit (#1474)."
+    },
+    {
+      "path": "tsconfig.base.json",
+      "bucket": "harness",
+      "note": "Shared TypeScript compiler base config."
+    },
+    {
+      "path": "tsconfig.json",
+      "bucket": "harness",
+      "note": "Root TypeScript project references config."
+    },
+    {
+      "path": "uv.lock",
+      "bucket": "harness",
+      "note": "uv dependency lockfile for the Python engine scripts."
+    },
+    {
+      "path": "vitest.config.ts",
+      "bucket": "harness",
+      "note": "Vitest config for the TS engine test suite."
+    },
+    {
+      "path": ".gitattributes",
+      "bucket": "repo-dev",
+      "note": "Git attributes (linguist/vendored markers, EOL); repository plumbing."
+    },
+    {
+      "path": ".github",
+      "bucket": "repo-dev",
+      "note": "GitHub Actions workflows, issue/PR templates, CODEOWNERS; maintainer CI only."
+    },
+    {
+      "path": ".gitignore",
+      "bucket": "repo-dev",
+      "note": "Git ignore rules; repository plumbing."
+    },
+    {
+      "path": ".planning",
+      "bucket": "repo-dev",
+      "note": "Maintainer planning artifacts (e.g. generated codebase MAP projection); never ships."
+    },
+    {
+      "path": "CHANGELOG.md",
+      "bucket": "repo-dev",
+      "note": "Maintainer changelog; promoted into GitHub release bodies at release time."
+    },
+    {
+      "path": "CONTRIBUTING.md",
+      "bucket": "repo-dev",
+      "note": "Maintainer contributor guide for the deft repo itself."
+    },
+    {
+      "path": "PRD.md",
+      "bucket": "repo-dev",
+      "note": "The deft project's own product requirements doc; not consumer framework content."
+    },
+    {
+      "path": "PROJECT.md",
+      "bucket": "repo-dev",
+      "note": "The deft project's own project doc (deprecation redirect / generated export); not consumer content."
+    },
+    {
+      "path": "README.md",
+      "bucket": "repo-dev",
+      "note": "GitHub-facing repository readme for the deft project."
+    },
+    {
+      "path": "REFERENCES.md",
+      "bucket": "repo-dev",
+      "note": "Repo-level references index for maintainers (harness-entry-adjacent; stays at root)."
+    },
+    {
+      "path": "ROADMAP.md",
+      "bucket": "repo-dev",
+      "note": "The deft project's own roadmap; updated at release time."
+    },
+    {
+      "path": "SPECIFICATION.md",
+      "bucket": "repo-dev",
+      "note": "The deft project's own generated specification export / deprecation redirect; not consumer content."
+    },
+    {
+      "path": "docs",
+      "bucket": "repo-dev",
+      "note": "Predominantly maintainer/repo docs (FILES.md, RELEASING.md, analysis/, audits, incident smoke records); the consumer-facing concept guides were promoted to content/docs/ (#1875 C3)."
+    },
+    {
+      "path": "history",
+      "bucket": "repo-dev",
+      "note": "Archived task/vBRIEF state preserved byte-for-byte as a forensic record; never ships."
+    },
+    {
+      "path": "incidents",
+      "bucket": "repo-dev",
+      "note": "The deft project's own incident postmortem records; the _template.md + README convention were promoted to content/incidents/ (#1875 C3)."
+    },
+    {
+      "path": "meta",
+      "bucket": "repo-dev",
+      "note": "Repo-dev meta: ideas.md, suggestions.md, lessons.md (pack projection target), policy-changes.log. The shippable meta docs were promoted to content/meta/ (#1875 C3)."
+    },
+    {
+      "path": "specs",
+      "bucket": "repo-dev",
+      "note": "The deft project's own framework spec fixtures/examples (strategy-chaining, testbed); repo-dev per #1669 Wave-1 C3 (not shipped)."
+    },
+    {
+      "path": "vbrief",
+      "bucket": "repo-dev",
+      "note": "The maintainer's own vBRIEF scope lifecycle (proposed/pending/active/completed/cancelled + PROJECT-DEFINITION) plus the framework's own migration RESULT artifacts at vbrief/migration/ (LEGACY-REPORT.md / RECONCILIATION.md / safety-manifest.json). The shippable vBRIEF surface (schemas/, vbrief.md) was promoted to content/vbrief/ (#1875 C3); the migration result records stay repo-dev (this repo's own migration output, not a consumer convention)."
+    }
+  ]
+}

package/conventions/machine-generated-banner.md

@@ -0,0 +1,130 @@
+# Machine-Generated File Banner (Canonical Contract)
+
+Canonical banner template emitted by every deft writer that produces a
+machine-managed markdown file. Defined to eliminate the four-convention
+drift surfaced in #572 (spec:render emitted none; migrator heuristic
+searched for strings no writer actually produced).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Why
+
+Before this contract, deft had four machine-managed file writers
+(`task migrate:vbrief` deprecation redirects, `task spec:render`,
+`task prd:render`, `task roadmap:render`) and each used a different
+(or no) banner convention. Downstream heuristics that distinguish
+"is this file user-customized" from "is this machine-managed" were
+decoupled from what the writers actually emitted -- a correctness
+risk, not a polish one.
+
+## The canonical 4-line banner
+
+! Every machine-managed markdown file MUST begin with exactly these
+four HTML-comment lines, in this order, as the very first four lines
+of the file:
+
+```
+<!-- AUTO-GENERATED by {generator} -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: {purpose} -->
+<!-- Source of truth: {source} -->
+<!-- Regenerate with: {command} -->
+```
+
+- `{generator}` — the human-readable writer name (e.g. `task spec:render`).
+- `{purpose}` — one of the enumerated per-writer purposes below; fixed
+  string values so downstream detectors can match on a stable token.
+- `{source}` — the source-of-truth path the writer consumed
+  (typically `vbrief/specification.vbrief.json`), or `n/a` when the
+  writer has no single source-of-truth file (e.g. the migrator
+  deprecation redirect, which is driven by the migration flow).
+- `{command}` — the canonical `task *` invocation that regenerates
+  the file; operators copy-paste from this line.
+
+! All four lines MUST be populated (no empty `{...}` placeholders).
+! The banner MUST be the first four lines of the file -- nothing
+  (not even blank lines) precedes it.
+
+## Per-writer purpose registry
+
+The `Purpose:` value is a small fixed enum so detectors can match on a
+stable token. Writers MUST use exactly one of these values:
+
+- `rendered specification` -- `scripts/spec_render.py` -> `SPECIFICATION.md`
+- `rendered PRD` -- `scripts/prd_render.py` -> `PRD.md`
+- `rendered roadmap` -- `scripts/roadmap_render.py` -> `ROADMAP.md`
+- `deprecation redirect` -- `scripts/migrate_vbrief.py::_deprecation_redirect()`
+  -> replaced `SPECIFICATION.md` / `PROJECT.md`
+
+? Future render tasks added under `tasks/` MUST extend this list before
+shipping; a new writer without a registered `Purpose:` value is a
+contract violation.
+
+## Detection heuristic (for user-customization guards)
+
+! `scripts/migrate_vbrief.py::_is_user_customized()` consults the
+`_SPEC_AUTO_MARKERS` and `_PROJECT_AUTO_MARKERS` tuples. Both MUST
+include `"AUTO-GENERATED by"` and the FULL HTML-comment prefix
+`"<!-- Purpose:"` so any file carrying this banner is recognised as
+machine-managed. The marker is deliberately the full `<!-- Purpose:`
+prefix and NOT the bare `Purpose:` string, so a hand-authored
+specification containing ordinary prose such as
+`"Purpose: deliver a self-service flow."` is not misclassified as
+machine-managed and silently overwritten.
+
+! Pre-cutover guards (e.g.
+`skills/deft-directive-setup/SKILL.md`) MUST accept BOTH the legacy
+`<!-- deft:deprecated-redirect -->` sentinel AND the current
+`Purpose: deprecation redirect` marker for at least one release
+cycle so consumers that migrated under rc.1 / rc.2 are not
+incorrectly re-flagged as pre-cutover on rc.3.
+
+## Example (spec:render)
+
+```
+<!-- AUTO-GENERATED by task spec:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered specification -->
+<!-- Source of truth: vbrief/specification.vbrief.json -->
+<!-- Regenerate with: task spec:render -->
+# My Project
+...
+```
+
+## Example (migrator deprecation redirect)
+
+```
+<!-- AUTO-GENERATED by task migrate:vbrief -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: deprecation redirect -->
+<!-- Source of truth: n/a -->
+<!-- Regenerate with: task migrate:vbrief -->
+<!-- deft:deprecated-redirect -->
+# SPECIFICATION.md -- DEPRECATED
+...
+```
+
+The legacy `<!-- deft:deprecated-redirect -->` sentinel remains on the
+fifth line of the deprecation redirect for one release cycle so
+existing detectors (consumer agents, pre-cutover guards, the
+migrator's own re-run protection in `_vbrief_safety.py`) continue to
+work while tooling upgrades to the canonical `Purpose:` token.
+
+## Regression test
+
+`tests/content/test_machine_generated_banner.py` parametrises over
+all four writers, invokes each on a fixture, and asserts:
+
+1. the output begins with the four canonical banner lines;
+2. all `{generator}`, `{purpose}`, `{source}`, `{command}`
+   placeholders are populated with the expected values;
+3. the `Purpose:` token is one of the four registered purposes.
+
+Guards the convention against future drift.
+
+## Cross-references
+
+- #572 — originating issue
+- `scripts/migrate_vbrief.py` — `_deprecation_redirect()`,
+  `_SPEC_AUTO_MARKERS`, `_PROJECT_AUTO_MARKERS`
+- `scripts/spec_render.py::_BANNER`
+- `scripts/prd_render.py::BANNER`
+- `scripts/roadmap_render.py::BANNER`
+- `skills/deft-directive-setup/SKILL.md` § Pre-Cutover Detection Guard

package/conventions/references.md

@@ -0,0 +1,120 @@
+# vBRIEF References — `x-vbrief/*` Type Registry
+
+Canonical reference for the shape and type registry of `plan.references` entries in vBRIEF files.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [../vbrief/vbrief.md](../vbrief/vbrief.md) | [../vbrief/schemas/vbrief-core.schema.json](../vbrief/schemas/vbrief-core.schema.json) | [../main.md](../../main.md)
+
+---
+
+## Schema-Conformant Reference Shape
+
+Every entry in `plan.references` is a `VBriefReference`, which extends the
+schema's `URI` object and adds a `type` field that MUST match the pattern
+`^x-vbrief/` (per the canonical v0.6 schema and directive's vendored copy).
+
+```json
+"references": [
+  {
+    "uri": "https://github.com/{owner}/{repo}/issues/{N}",
+    "type": "x-vbrief/github-issue",
+    "title": "Issue #{N}: {issue title}"
+  }
+]
+```
+
+Required fields:
+
+- ! `uri` — the canonical URL or relative path (required by the `URI` base type; not `url`)
+- ! `type` — MUST begin with `x-vbrief/` (see registry below)
+
+Optional (schema-defined) fields:
+
+- ? `title` — a short human label (use `#{N}: {issue title}` for GitHub issues)
+- ? `description` — longer free-form context
+- ? `tags` — array of strings for categorization
+
+- ⊗ Use `url` as the field name — the schema requires `uri`
+- ⊗ Use `type` values outside `x-vbrief/*` (e.g. `"github-issue"` with no prefix) — strict validators will reject them
+- ⊗ Rely on `id` to convey issue numbers — that field is not schema-defined; put the issue number in `title` instead
+
+## `x-vbrief/*` Type Registry
+
+The following `type` values are recognized by deft's tooling and skills. Any
+`x-vbrief/*` value is schema-valid, but the types below carry documented
+semantics.
+
+- `x-vbrief/plan` — reference to another vBRIEF plan (epic→story or story→epic links, also the canonical v0.5 enum value)
+- `x-vbrief/github-issue` — a GitHub issue (the origin of an ingested scope vBRIEF, or a related issue)
+- `x-vbrief/github-pr` — a GitHub pull request (implementing PR, related PR, or superseded PR)
+- `x-vbrief/jira-ticket` — a Jira ticket (origin provenance for Jira-backed projects)
+- `x-vbrief/user-request` — a direct user request captured verbatim (no external tracker ID)
+- `x-vbrief/spec-section` — a pointer into `specification.vbrief.json` by item id or narrative key (traceability link for FR/NFR requirements)
+
+Consumer projects ? MAY extend the registry with additional `x-vbrief/*` values. When you do, document them in a project-local conventions file and cite them from `PROJECT-DEFINITION.vbrief.json`.
+
+### Additive sibling fields
+
+`References` entries MAY carry additional sibling fields alongside the schema-defined `uri` / `type` / `title` / `description` / `tags`. The following extension is recognised by deft tooling:
+
+- `TrustLevel` (`verified` | `internal` | `external`) -- source-trust classification, sourced from the AI Agent Traps paper's Cognitive State / Latent Memory Poisoning trap class. Canonical field shape, value enum, and rule body live in [`../vbrief/vbrief.md`](../vbrief/vbrief.md) `### TrustLevel (#480)`. The safe default for a missing field is `external` (#480).
+
+## Origin Provenance (D11)
+
+Scope vBRIEFs in `vbrief/pending/` and `vbrief/active/` SHOULD carry at least
+one reference whose `type` matches `^x-vbrief/`. `scripts/vbrief_validate.py`
+treats any `x-vbrief/*`-typed reference as an origin for the D11 check by
+default (schema-trusting behavior).
+
+Run the validator with `--strict-origin-types` to instead require an exact
+match against the registry above (allow-list behavior). Teams that want to
+enforce the allow-list in CI can opt in via the same flag.
+
+- ! Every ingested scope vBRIEF MUST carry at least one `references` entry linking to its origin
+- ~ Prefer registry types over ad-hoc `x-vbrief/*` values when a registry type fits
+
+### `Origin` narrative -- canonical provenance signal (#1096)
+
+For scope vBRIEFs ingested from a GitHub issue, the canonical provenance
+signal is the `plan.narratives.Origin` text emitted by
+`scripts/issue_ingest.py::_build_issue_vbrief`:
+
+- ! `Origin` MUST take one of these two forms:
+  - `Ingested from https://github.com/{owner}/{repo}/issues/{N}` (browser URL resolves)
+  - `Ingested from issue #{N}` (no-URL fallback)
+- `vBRIEFInfo.description` SHOULD mirror this as `Scope vBRIEF ingested from GitHub issue #{N}` (the secondary signal used by the dedup pass when `Origin` is absent).
+
+The dedup pass in `task issue:ingest -- <N>` differentiates *provenance*
+from *informational* references using this narrative:
+
+- A pre-existing vBRIEF blocks ingest of `#N` only when BOTH conditions hold:
+  1. The vBRIEF carries an `x-vbrief/github-issue` reference whose `uri`
+     points at `#N`.
+  2. The vBRIEF's `plan.narratives.Origin` (or `vBRIEFInfo.description`)
+     identifies the SAME `#N` as its provenance.
+- A vBRIEF with `Origin` pointing at `#X` and a companion `x-vbrief/github-issue` reference to `#Y` (`X != Y`) is the *provenance owner of #X only*. The reference to `#Y` is informational and MUST NOT block `task issue:ingest -- Y`.
+- Legacy v0.5-shape vBRIEFs that predate the `Origin` convention fall back
+  to a position-aware heuristic: the FIRST `x-vbrief/github-issue` reference
+  in `plan.references` is the implied provenance. This preserves dedup for
+  unmigrated trees and is bounded -- the canonical Origin signal is
+  authoritative whenever it is present.
+
+- ⊗ Treat every `x-vbrief/github-issue` reference as dedup-blocking provenance regardless of `Origin` -- that was the #1096 false-positive surface
+- ⊗ Mutate a `completed/` vBRIEF to remove a companion / sibling reference solely because `task issue:ingest` false-positives on it (rewriting completed history is an anti-pattern per `skills/deft-directive-refinement/SKILL.md`)
+- ~ When adding a companion / sibling / related-plan reference to an ingested vBRIEF, keep `Origin` pointing at the original ingest source so the dedup pass continues to recognise the vBRIEF as the canonical owner of that issue
+
+## Schema Version: v0.6 (Canonical, Strict)
+
+- ! All vBRIEFs MUST emit `"vBRIEFInfo": { "version": "0.6" }`
+- ! `scripts/vbrief_validate.py` accepts ONLY `"0.6"`; any other version (including legacy `"0.5"`) is a hard validation error
+- ! The vendored schema at `../vbrief/schemas/vbrief-core.schema.json` is the canonical v0.6 copy from [`deftai/vBRIEF`](https://github.com/deftai/vBRIEF/blob/master/schemas/vbrief-core-0.6.schema.json) and pins `vBRIEFInfo.version` to `const: "0.6"`
+- ! `scripts/migrate_vbrief.py` emits `"0.6"`; pre-existing v0.5 vBRIEFs are swept to `"0.6"` as part of the migrator flip PR
+
+## Anti-Patterns
+
+- ⊗ Write references with a bare `"type": "github-issue"` — the schema requires `^x-vbrief/`
+- ⊗ Write references with `"url"` instead of `"uri"`
+- ⊗ Rely on a custom `"id"` field for issue numbers — encode it in `title` (or `description`) instead
+- ⊗ Invent new non-prefixed type vocabularies — use `x-vbrief/*` everywhere
+- ⊗ Leave scope vBRIEFs in `pending/` / `active/` without any `x-vbrief/*` origin reference