Discoverability gap: Charters not surfaced through canonical onboarding (DEVTRAIL.md, agent skills, /devtrail-status)

[montfort]

Context

Working on a real greenfield project (Rust CLI/TUI suite) that uses DevTrail + SpecKit together as the governance stack. After the agent (Claude Opus 4.7) completed /speckit-constitution, /speckit-specify, /speckit-plan, /devtrail-adr (workspace adoption), /speckit-tasks (44 tasks across 6 phases), and /speckit-analyze, it never surfaced Charters as a relevant concept.

The project owner had to ask explicitly: "What's the strategy for the DevTrail Charters considering tasks.md?" — at which point the agent recognized the gap and produced 5 granularity options.

This issue documents the systemic discoverability gap behind that oversight, since it's likely reproducible with any agent (Gemini, Copilot, etc.) onboarding to a DevTrail+SpecKit project via the canonical entry points.

What didn't happen

A capable, attentive agent following the canonical project onboarding (DEVTRAIL.md, the project constitution, CLAUDE.md checklist, available /devtrail-* skills, /devtrail-status) did not autonomously identify Charters as a workflow concept during plan/tasks generation, even though the project clearly fit their use case (multi-session implementation, multi-phase tasks, audit value).

Charters were eventually adopted (2 Charters: foundation + MVP) only after explicit user prompt.

Root-cause analysis (9 contributing factors, grouped)

Documentation gaps

1. DEVTRAIL.md doesn't list Charters as a top-level type. The doc enumerates 12+4 document types (AILOG/AIDEC/ETH/SBOM/DPIA/PIPIA/TC260RA/AILABEL/ADR/REQ/TES/INC/TDE/SEC/MCARD). Charters are absent. Agents that build their mental model of DevTrail from this doc will not include Charters.

2. CLAUDE.md Pre-commit Checklist has no Charter trigger. The 6 checklist items map to AILOG/AIDEC/ADR/ETH/MCARD/SEC. None says "starting a multi-session implementation block? → declare a Charter."

3. Project constitutions written from DevTrail patterns inherit the gap. When project owners write their own constitutions (as Spec Kit's /speckit-constitution template encourages), they replicate the DevTrail abstractions they were exposed to. Charters get lost in transmission downstream.

Skill surface gaps

4. No /devtrail-charter-new (or equivalent) skill. Skill-driven discovery yields: /devtrail-adr, /devtrail-aidec, /devtrail-ailog, /devtrail-mcard, /devtrail-sec, /devtrail-new, /devtrail-status. Charters are not creatable through any skill. Agents that discover DevTrail through "what slash commands exist?" miss them.

5. /devtrail-status excludes Charters from its scan. The status skill explicitly enumerates 12 document prefixes (AILOG-, AIDEC-, ADR-, …) and counts only those. Even when an agent runs /devtrail-status to verify compliance, Charters are structurally invisible. The compliance-observability tool has a blind spot.

6. /devtrail-audit-* skills mention Charter in their descriptions ("Generate the unified audit prompt for a Charter at the canonical filesystem location") but the framing is external audit tooling, not Charter lifecycle terminus. The connection "Charter = work unit; audit-* = its closure" requires reading the Charter template — which agents may not do unprompted.

Template-level gaps

7. charter-template.md and charter-telemetry-template.yaml are listed in .devtrail/templates/ but indistinguishable from auxiliary templates. They sit alongside TEMPLATE-ADR.md etc. An agent triaging templates by relevance will skip them.

Workflow integration gaps

8. No documented bridge between SpecKit and DevTrail Charters. The Charter frontmatter has originating_spec: specs/NNN-feature/spec.md — the perfect bridge. But no doc explains when a SpecKit feature should yield a Charter, how granular (1 per feature? 1 per phase? 1 per User Story?), or who triggers the creation (/speckit-tasks close? before /speckit-implement?).

9. Agents form binary mental models of multi-tool workflows. "SpecKit = planning, DevTrail = audit-trail." Charters represent a third layer (work-as-auditable-shippable-unit) that doesn't fit either category. Without explicit naming in canonical docs, the binary model dominates and the third layer is silently discarded.

Suggested remediation (low-cost, reversible)

Priority order, smallest blast radius first:

High impact / low cost

• Add Charter section to DEVTRAIL.md as a top-level type. Brief description, when to create, link to template. Equivalent rank to ADR.
• Add Charter trigger to CLAUDE.md template's Pre-commit Checklist: "Starting a multi-session implementation block (>1 day, >5 tasks)? → Declare Charter in .devtrail/charters/."
• Update /devtrail-status skill to scan .devtrail/charters/*.md, display open/in-progress/closed counts, list active Charters with their task ranges.

Medium impact / medium cost

• Create /devtrail-charter-new skill that scaffolds CHARTER-NN.md from the template with frontmatter pre-filled. Analogous to /devtrail-adr.
• Document the SpecKit ↔ Charter bridge in DevTrail's main docs: when a feature spec yields a Charter, granularity heuristics (1 Charter per shippable unit, NOT per User Story or per feature; effort_estimate M-L is the sweet spot), creation timing (after /speckit-tasks, before /speckit-implement).
• Add /devtrail-charter-close skill that updates status, prompts for telemetry yaml, optionally chains to /devtrail-audit-prompt.

Low impact / low cost

• Reorganize .devtrail/templates/: move charter-template.md and charter-telemetry-template.yaml into a charter/ subdirectory, signaling "this is a workflow concept, not a doc template."
• Cross-reference: in /devtrail-new skill description, mention Charters as the unit-of-work concept that contains the docs /devtrail-new creates.

Reproducibility

This pattern is likely to repeat with any agent (Claude, Gemini, Copilot) onboarding to a DevTrail+SpecKit project via the canonical entry points. The gap is systemic, not session-specific — fixing it benefits all future agent interactions.

Empirical context

• Project: greenfield Rust CLI/TUI suite, v0.1.
• Agent: Claude Opus 4.7 (1M context).
• Workflow phase when gap manifested: between /speckit-tasks and /speckit-implement.
• Time to detect: ~6 hours of session work; never autonomously surfaced.
• Time to resolve once user prompted: ~5 minutes (agent immediately produced 5 granularity options, recommended a 2-Charter strategy).
• Outcome: 2 Charters being created (Foundation + MVP) after this issue is filed.

Acknowledgment

Filed by a real DevTrail user as part of using the framework on a real project. Not a hypothetical. Happy to provide additional artifacts (the relevant session transcript, the resulting Charter files, the resulting tasks.md) if useful for triage.

[montfort]

Fix submitted in PR #122 (feat/charter-discoverability-113).

Note: this PR depends on PR #121 (the path-fix from #119) because the new straymark status Charter block uses the charters_dir() helper introduced there. Merge order: #121 → #122. Both issues should close on the same merge wave.

Coverage of the 9 root causes:

#	Root cause	Where it's addressed in PR #122
1	STRAYMARK.md doesn't list Charters as a top-level type	New §15 dedicated to Charters; rows in §6, §9, §10, §11, §13
2	CLAUDE.md Pre-commit Checklist has no Charter trigger	Charter trigger row added to dist/dist-templates/directives/{CLAUDE,GEMINI,copilot-instructions}.md
3	Project constitutions inherit the gap	Constitution authoring isn't in this repo's surface, but the SPECKIT-CHARTER-BRIDGE.md doc gives operators the language to encode it correctly when they author one
4	No /straymark-charter-new skill	New skill added across .claude/skills/, .gemini/skills/, .agent/workflows/
5	/straymark-status excludes Charters	(a) Skill (×3) updated to scan .straymark/charters/ and surface gaps; (b) cli/src/commands/status.rs gains a "Charters" block with declared/in-progress/closed counts, sourced from the same charter::discover_and_parse that charter list uses
6	/straymark-audit-* framing as external-tooling vs lifecycle-terminus	Lifecycle table added to STRAYMARK.md §15 and SPECKIT-CHARTER-BRIDGE.md makes the audit step explicitly the closure phase of a Charter
7	Templates indistinguishable from auxiliary	charter-template.md and charter-telemetry-template.yaml moved to dist/.straymark/templates/charter/ subdirectory (with i18n/es/ translation co-located). CLI updated to load from the subdir
8	No SpecKit ↔ Charter bridge documented	New dist/.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md (EN + ES + zh-CN). Documents 4 yes-conditions, 3 no-conditions, 4 granularity heuristics ("one Charter per shippable cut, NOT per User Story"), creation timing within the SpecKit pipeline, frontmatter linkage in both directions, 5 anti-patterns, 5 non-fit cases
9	Binary mental models silently drop the third layer	The combined effect of items 1, 4, 5, 8 above — Charter is now named in every entry point an agent uses to build its mental model

Out of scope (deliberately deferred):

• /straymark-charter-{list,status,close,audit} skills — CLI subcommands cover those operations directly; duplicating as skills would add surface without an operational hook the user can't already get from straymark charter <verb>. Only new got a skill because that's the discovery point.
• Schema change: backfilling originating_charter: field into AILOG schemas. The slot is already permitted via additionalProperties; a follow-up PR can lock it formally.

Empirical context preserved:

The PR cites the original session — greenfield Rust CLI/TUI suite, Claude Opus 4.7, gap detected between /speckit-tasks and /speckit-implement, eventually adopted 2 Charters (foundation + MVP) only after explicit user prompt. The SPECKIT-CHARTER-BRIDGE.md examples use that exact case (specs/001-peek-mvp-foundation/ → CHARTER-01 + CHARTER-02) so future readers see the pattern in its native form.

Will close once PR #122 merges to main (after #121).