RFC: TDE document type has no activation trigger — formalize when to file TDE vs in-charter R<N> (emerged from Sentinel CHARTER-13 retrospective)

[montfort]

Context

StrayMark defines the TDE (Technical Debt) document type with:

• Template at .straymark/templates/TEMPLATE-TDE.md
• Destination .straymark/06-evolution/technical-debt/
• Agent autonomy: Identify (agent creates; human prioritizes/assigns)
• Frontmatter with type, impact, effort, priority: null, assigned_to: null

This is the right shape for transversal technical debt that needs human prioritization. But in Sentinel (primary adopter, fw v4.12.0), the TDE type has never been activated — zero TDEs in .straymark/06-evolution/technical-debt/ after 13 closed Charters covering two specs.

This RFC argues the cause is missing activation trigger in the framework guidance, and proposes how to fix it.

Empirical observation

Across CHARTER-01 → CHARTER-13 (Sentinel), at least 7 instances of cross-charter technical debt were identified but routed via parallel mechanisms instead of TDE:

Mechanism	Used where	Coverage
R<N> (new, not in Charter) in AILOG §Risk	Charter-scoped, emergent risks (CHARTER-07 R6-R11, CHARTER-08 R6-R9, CHARTER-13 R6-R8)	Ágil, lives where decisions are made; no priority, no assigned_to, scoped to one Charter
.straymark/follow-ups-backlog.md + scripts/check-followups-drift.sh (RFC #111 — closed)	Cross-charter pending items extracted from §Follow-ups + R<N>(new) blocks	Solves the aggregation gap but not the formalization gap (freeform text, not typed governance documents, no impact/effort matrix)
Inline legends in tasks.md	→ CHARTER-14 / → T103 polish per-task arrows	Trace-only; no governance metadata

None of these produces a TDE document, so:

• No queryable "all open technical debts" view at the document level.
• No impact × effort prioritization matrix per item.
• No assigned_to / priority fields surfaced to the human reviewer.
• Architectural debt that legitimately spans multiple charters (e.g., scope authorization gap heritage across modules) gets fragmented into per-charter R-numbers instead of consolidated into a single TDE.

Concrete examples from CHARTER-13 (just closed)

Three findings from the CHARTER-13 audit cycle (gemini-2-5-pro + gpt-5.3-codex cross-family pair) that should have been TDEs but were filed as R-numbers + follow-ups:

1. R7 — RequireScope architectural gap (heritage from CHARTER-08).
   middleware/scopes.go RequireScope is a helper handlers must call explicitly; neither US1 (CHARTER-08) nor US2a (CHARTER-13) handlers call it. Heading-level comments claim "gated by scope" but enforcement is 0% at HTTP layer; only RLS provides tenant isolation, NOT scope authorization. Type: architecture. Impact: high. Effort: medium (~2h dedicated charter touching US1 + US2a in one PR). Risk if unresolved: medium-high. This is exactly the TDE shape — transversal, requires dedicated charter, requires human prioritization. It was routed as "follow-up to a dedicated auth-hardening charter" in AILOG-041 §Risk R7.

2. HTTP layer test coverage gap (calibrator-discovered, missed by both auditors). Integration tests T040/T041/FR-005 sub-tests call env.svc directly, not through HTTP handlers. The 7 huma operations registered are not exercised end-to-end with real middleware. Type: testing. Impact: medium. Effort: medium (~1-2h httptest scaffolding + sub-tests). Cross-module testing debt — applies to US1 + US2a today and will apply to every future US.

3. Legacy AILOGs with risk_level: high + review_required: false (CHARTER-04 explicitly deferred 8 sensitive docs to "human review case-by-case"; 2 of those just surfaced via PR fix(cli): code-block bg fragments on narrow panels (cli-3.4.1) #58 CI gate during a rebrand). Type: documentation/governance. Impact: medium. Effort: medium (real security audit per doc). Documentation debt that has lived in the repo since April 2026 without a queryable surface.

Why the trigger didn't fire

Reading the adopter-facing docs (AGENT-RULES.md, DOCUMENTATION-POLICY.md, QUICK-REFERENCE.md, CLAUDE.md autonomous rules), there is no clear trigger that says "create a TDE now". The trigger language exists for AILOG (creation freely), AIDEC (when alternatives considered), ETH (high risk PII), ADR (architectural decisions), but TDE is just listed as "agent can Identify".

When an agent (or human) encounters technical debt during Charter execution, the path of least resistance is:

1. Add an R<N> (new, not in Charter) in the AILOG §Risk (already part of the Charter flow)
2. Or add a §Follow-ups entry (auto-extracted to .straymark/follow-ups-backlog.md)

Both are lighter-weight than opening a new TDE document. So TDE never fires.

Proposed resolution

1. Document the heuristic explicitly in AGENT-RULES.md / DOCUMENTATION-POLICY.md

Add a "When to file TDE vs R" decision table. Suggested wording:

R in AILOG §Risk: emergent risk scoped to the Charter currently in execution or the next Charter. Resolvable as a documented deferral, a small atomic fix, or a forward-pointer to a charter that already exists. Low-medium impact.

TDE: technical debt transversal to multiple Charters or modules, requires dedicated effort outside the current Charter's scope envelope, medium-high impact, OR requires human prioritization/assignment that the agent cannot decide alone (e.g., "Which team owns this?"). Architectural gaps, cross-module testing gaps, legacy documentation debt all fit here.

Concrete trigger phrases that should result in a TDE rather than an R:

• "…heritage from CHARTER-XX" (the debt predates the current Charter)
• "…routed to a dedicated charter" (resolution requires a new Charter, not the next one in flow)
• "…applies to multiple modules" (transversal)
• "…requires human prioritization" (impact/effort matrix needs human judgment)

2. Cross-link TDE from follow-ups-backlog.md

The follow-ups-backlog.md workflow (RFC #111) is designed for the aggregation layer. TDE is designed for the formalization layer. They should co-exist:

• A follow-up entry under bucket charter-triggered can be promoted to a TDE when the agent (or human reviewing the backlog) determines it meets the transversal threshold.
• The TDE frontmatter could carry a promoted_from_followup: FU-NNN field for traceability.
• The drift script (scripts/check-followups-drift.sh) could optionally suggest TDE promotion candidates by flagging entries that have lived in the backlog through ≥2 Charters without resolution.

3. Add TDE creation to straymark-new / straymark-status skill prompts

Currently the skills surface AILOG, AIDEC, ETH, ADR, etc. but not TDE explicitly. Adding TDE to the skill prompt's "consider creating" list (with the trigger heuristic above) would surface the option to agents during Charter execution.

4. Optional: straymark debt list CLI

If the adopter usage justifies it, a straymark debt list/status/close CLI trio (mirroring straymark followups list/close/drift from RFC #111) would let adopters query open TDEs by impact × effort matrix without grepping .straymark/06-evolution/technical-debt/.

Adoption plan (post-acceptance)

Sentinel will create the 3 TDEs identified above in a follow-up PR after framework guidance lands. We're happy to be the empirical validation testbed for the trigger heuristic — same role Sentinel played for the audit-skills v1 cycle (issue #102) and the follow-ups backlog (issue #111).

Acknowledgements

Surfaced during Sentinel CHARTER-13 close ceremony retrospective (operator question: "hay un documento técnico especializado de StrayMark para reportar deuda técnica? por qué no lo hemos usado?"). The honest answer was: "yes, but the trigger never fired." This RFC is the fix.

---

🤖 Issue body co-authored with Claude Code (Sentinel adopter agent).

[montfort]

Resolution lands in #129 (branch `feat/tde-activation-trigger`, fw-4.13.0). Scope reduced to governance-docs-only per the RFC's adoption plan; CLI deferred to v1 against a second-adopter validation gate (same gate FOLLOW-UPS-BACKLOG-PATTERN.md applied to the `straymark followups` CLI). Notes below on what entered, what didn't, and one collateral finding.

What the verification confirmed

The RFC's central claim — TDE has shape but no operational activation trigger — is empirically correct. Verified by reading the framework's three "When to Document" tables (`AGENT-RULES.md §2`, `QUICK-REFERENCE.md`, `STRAYMARK.md §6`): every other doc type (AILOG, AIDEC, ETH, ADR) has an explicit trigger row; TDE has none. The only operational mention of TDE in agent-facing governance was the exhortation "Alert about technical debt" in `AGENT-RULES.md §6 "Be Proactive"` — aspirational, no criteria.

What the verification refuted, partially

The RFC's claim that `/straymark-new` and `/straymark-status` don't surface TDE is technically inaccurate:

• `straymark-new/SKILL.md:57` already had `"TODO, FIXME, HACK comments added → TDE"`
• `straymark-status/SKILL.md:34` already tracked TDE counts

The spirit holds, though: that trigger is a code-smell trigger (literal `// TODO` comments), not the architectural trigger the RFC actually argues for (transversal debt requiring a dedicated Charter). So the fix is to extend the suggestion table, not add TDE from scratch. Both rows now coexist — code-smell + architectural.

What landed in #129

Governance triggers (EN + ES + zh-CN)

• `AGENT-RULES.md §2` — new TDE row in "When to Document"
• `AGENT-RULES.md §3` — new "TDE vs `R` (new, not in Charter)" section with the four canonical criteria you proposed:
  • heritage from a prior Charter
  • applies to multiple modules/Charters
  • requires a dedicated Charter outside the current scope envelope
  • requires human prioritization/assignment the agent cannot decide alone
• `QUICK-REFERENCE.md` "When to Document" — TDE row pointing back to `AGENT-RULES.md §3`
• `STRAYMARK.md §6` — TDE row

FU → TDE promotion path

`FOLLOW-UPS-BACKLOG-PATTERN.md` (EN + ES + zh-CN) gains:

• New status: `promoted`
• New `Destination` value: `TDE-YYYY-MM-DD-NNN`
• New entry field: `Promoted to:`
• New section "Promotion to TDE" with promotion criteria (mirroring `AGENT-RULES.md §3`) + operator-driven workflow (periodic review / Charter close review / pre-Charter declaration)
• Post-Charter-close agent checklist now includes "promote un-resolved transversal entries to TDE"

Template (EN + ES + zh-CN)

• `TEMPLATE-TDE.md` frontmatter gains `promoted_from_followup: FU-NNN | null`
• Body gains inline activation-triggers note pointing to `AGENT-RULES.md §3` (read at creation time)

Skill `/straymark-new` (3 surfaces)

• TDE suggestion row split: code-smell trigger preserved + architectural trigger added

Collateral finding (fixed in the same PR)

While verifying the TDE flow end-to-end, `/straymark-status` (3 surfaces — `.claude/`, `.gemini/`, `.agent/`) turned out to have five doc-type paths diverging from the canonical layout in `AGENT-RULES.md §5` and `STRAYMARK.md §10`:

Type	Was	Now
ADR	`04-architecture/decisions/`	`02-design/decisions/`
REQ	`03-requirements/`	`01-requirements/`
TES	`05-testing/`	`04-testing/`
INC	`06-operations/incidents/`	`05-operations/incidents/`
TDE	`06-operations/tech-debt/`	`06-evolution/technical-debt/`

The TDE bug was load-bearing for this RFC: `/straymark-new` would have written to the correct path and `/straymark-status` would have looked in the wrong one — feature silently broken. Same one-character drift on the other four, fixed in the same pass since they share the cause. Same correction applied to the `/straymark-adr` row in `CLI-REFERENCE.md` (3 langs).

What's deliberately out (deferred to v1)

• `straymark debt list/status/close` CLI subcommand trio
• `check-followups-drift.sh` enhancement to flag TDE promotion candidates

Both deferred against the second-adopter validation gate per `FOLLOW-UPS-BACKLOG-PATTERN.md:179`. The trigger heuristic needs empirical validation by Sentinel (creating the three CHARTER-13 TDEs) plus a second adopter before the CLI surface crystallizes.

Next step — empirical validation gate

Before tagging `fw-4.13.0` stable, the three TDEs from CHARTER-13 close-ceremony retrospective should be created in Sentinel as the empirical proof that the trigger heuristic works:

1. R7 RequireScope architectural gap — heritage from CHARTER-08, US1 + US2a, ~2h dedicated charter
2. HTTP layer test coverage gap — cross-module testing debt, ~1-2h httptest scaffolding
3. Legacy AILOGs with `risk_level: high` + `review_required: false` — documentation/governance debt since April 2026

If the heuristic doesn't fire cleanly on all three (or fires on cases it shouldn't), the criteria need refinement before stable tag.

Related, out of scope here

The verification also surfaced a pre-existing validator bug — `straymark validate` rejects `status: identified` with `META-003` even though it's the canonical TDE default per `DOCUMENTATION-POLICY.md §6`. Reproduces against `main` without #129's changes; filed as a separate issue.

[montfort]

Empirical validation gate complete — 3 TDEs filed (Sentinel PR #61, merged)

Closing the loop on this RFC's ## Next step — empirical validation gate. The full chain:

1. Sentinel CHARTER-13 retrospective surfaces the gap (this RFC).
2. Upstream feat(framework): fw-4.13.0 — TDE activation trigger (closes #128) #129 lands the v4.13.0 governance triggers, FU → TDE promotion path, template extensions, skill row split, and the collateral /straymark-status path bug-fix.
3. Sentinel framework sync StrangeDaysTech/sentinel#60 adopts fw-4.13.0 with zero Go-code changes.
4. Sentinel empirical validation StrangeDaysTech/sentinel#61 — this PR — files the 3 TDEs proposed in the RFC's adoption plan, exercising the v4.13.0 trigger heuristic across three different Debt Types.

The 3 TDEs filed

TDE	Title	Priority	Type	Effort	Triggers (of 4 canonical)
TDE-2026-05-11-001	CommsHub RequireScope architectural gap	P1	architecture	~2h	4/4
TDE-2026-05-11-002	CommsHub HTTP layer test coverage gap	P2	testing	~1-2h	3/4
TDE-2026-05-11-003	2 legacy MVP AILOGs pending human review	P3	documentation	~1.5-2h	3/4

Each TDE includes the activation triggers note at the top (per the v4.13.0 template), full problem analysis, proposed solution with alternatives, effort/impact/urgency estimation, prioritization matrix, and the new promoted_from_followup frontmatter field pointing to the new backlog FU entries (FU-048 / FU-049 / FU-050).

Heuristic empirical observations

What worked cleanly (no ambiguity):

• TDE-001 — all 4 canonical triggers apply unambiguously. The gap originates in a prior closed Charter (CHARTER-08), affects multiple closed Charters (CHARTER-08 + CHARTER-13), requires a dedicated Charter to fix (mixes scope across closed Charters), and requires human prioritization (security vs feature pacing). Textbook trigger application.

• TDE-002 — 3 of 4 triggers apply cleanly. "Heritage" is marginal (see below).

• TDE-003 — 3 of 4 triggers apply cleanly. "Multi-module" is marginal (see below).

Two trigger-language refinement suggestions (non-blocking — can land in fw-4.13.1):

1. heritage from a prior Charter could be ambiguous on TDE-002's case: the gap originated in CHARTER-08 but isn't truly "inherited" — it's that CHARTER-13 unwittingly reproduced the same pattern. Distinct meanings:

   • strict heritage: the prior Charter introduced the debt; subsequent Charters merely propagate it without re-introducing it (e.g., legacy DB schema decision)
   • pattern propagation: the prior Charter set a pattern; subsequent Charters re-introduce the same debt by following the pattern

   Both are TDE-worthy, but the trigger text reads as the first interpretation. Suggestion: amend AGENT-RULES.md §3 to include both with examples.

2. applies to multiple modules/Charters could be ambiguous on TDE-003's case: the debt is in only 2 specific AILOG documents (not multiple Charters or modules in the structural sense). But the governance impact crosses multiple Charter boundaries (CHARTER-04 deferred, CHARTER-08 → CHARTER-13 passed silently, only surfaced in PR fix(cli): code-block bg fragments on narrow panels (cli-3.4.1) #58 rebrand). Suggestion: clarify the trigger applies to "multiple modules or Charter execution boundaries", to include governance-trail debt that spans sessions without spanning code modules.

Both refinements are textual clarifications; the heuristic captured all 3 TDEs correctly even with the current wording. Not blockers for fw-4.13.0 stable.

FU → TDE promotion path testing

.straymark/follow-ups-backlog.md extended per FOLLOW-UPS-BACKLOG-PATTERN.md fw-4.13.0:

• New section ## Promoted to TDE with 3 entries (FU-048, FU-049, FU-050) cross-linking each TDE
• Each entry: Status: promoted, Destination: TDE-YYYY-MM-DD-NNN, Promoted to: TDE-YYYY-MM-DD-NNN, provenance pointing back to the R-number / calibrator review / CHARTER-04 deferral source

One observation on the promotion path: the current pattern doc says "leave it in place with the new status" assuming the FU already existed as open. Our 3 cases were retroactively created — they did NOT pre-exist as open FUs, they nacieron como promoted. The pattern works for this case (no harm done) but doesn't explicitly cover it. Suggestion: amend FOLLOW-UPS-BACKLOG-PATTERN.md §"Promotion to TDE" to document the "retroactive promotion at creation" case alongside the standard "promote existing open FU" case. Again non-blocking for stable.

Schema extension

Added total_promoted: 3 to the backlog header. This mirrors the existing total_open / total_closed_in_session / total_phase_blocked pattern. If you'd like to canonicalize this as part of the schema v1 (alongside the FU → TDE promotion path), happy to draft.

Recommendation for fw-4.13.0 stable tag

Ready for stable tag. The heuristic fired cleanly on all 3 cases without ambiguity at the decision-making level. The two trigger-language refinements + the retroactive-promotion case can land in fw-4.13.1 without blocking adoption.

The CLI subcommand trio (straymark debt list/status/close) deferred to the second-adopter validation gate — still appropriate; Sentinel's single-adopter feedback isn't enough to crystallize CLI surface decisions.

cc @montfort (Sentinel maintainer + RFC author) for visibility.

---

🤖 Comment co-authored with Claude Code (Sentinel adopter agent).