Charter: ADR-0012 ("legacy-param debt is real and in scope") · needs versioned-deprecation discipline
Problem
brain_write's schema carries legacy params from before the wing/hall model: domain, type, and the knowledge/ landing path (the description literally says "(legacy)" several times). They're live API surface, so every caller has to read past them, and the two code paths (legacy knowledge/ write with old frontmatter vs. wing+hall wiki/ write) mean brain_write has two behaviours depending on which optional fields are set. That's exactly the mechanism-leak + surface-rot ADR-0012 warns about.
What to do (versioned deprecation, NOT a hard break)
Audit callers — grep SKILLs, agents, agentsquad, harvest paths, capture's BrainStore for any use of domain/type/the knowledge/ path. Capture the real usage before changing anything.
Mark deprecated — annotate the legacy params in the schema/description as deprecated with the wing/hall replacement, so no new caller adopts them.
Migrate live callers to wing/hall.
Collapse the code path — once no caller uses the legacy fields, remove them and the knowledge/-landing branch so brain_write has one behaviour.
Caution: the knowledge/ vs wiki/ distinction is curation-state (per #43 — unreviewed vs promoted), not just legacy cruft. Confirm the promote/pending flow (#38) doesn't depend on the knowledge/ write path before removing it. If it does, that path's removal is gated on the promote-verb work, not free.
Acceptance
Caller audit complete (who, if anyone, uses domain/type/knowledge-path)
Legacy params marked deprecated in the schema
Live callers migrated to wing/hall
knowledge/-path dependency on the promote flow (#38) confirmed or ruled out before removal
Legacy params + dead code path removed; brain_write has one behaviour
task check green; existing brain_write/update tests still pass
Related
ADR-0012 (legacy-param debt) · #43 (knowledge/ vs wiki/ is curation-state, not cruft) · #38 (promote flow that may depend on knowledge/) · sibling #78 (brain_index)
**Charter:** ADR-0012 ("legacy-param debt is real and in scope") · needs versioned-deprecation discipline
## Problem
`brain_write`'s schema carries legacy params from before the wing/hall model: `domain`, `type`, and the `knowledge/` landing path (the description literally says "(legacy)" several times). They're live API surface, so every caller has to read past them, and the two code paths (legacy `knowledge/` write with old frontmatter vs. wing+hall `wiki/` write) mean `brain_write` has two behaviours depending on which optional fields are set. That's exactly the mechanism-leak + surface-rot ADR-0012 warns about.
## What to do (versioned deprecation, NOT a hard break)
Per ADR-0012's migration discipline — add-new / deprecate-old / migrate-callers / then-remove:
1. **Audit callers** — grep SKILLs, agents, agentsquad, harvest paths, capture's BrainStore for any use of `domain`/`type`/the knowledge/ path. Capture the real usage before changing anything.
2. **Mark deprecated** — annotate the legacy params in the schema/description as deprecated with the wing/hall replacement, so no *new* caller adopts them.
3. **Migrate live callers** to wing/hall.
4. **Collapse the code path** — once no caller uses the legacy fields, remove them and the `knowledge/`-landing branch so `brain_write` has one behaviour.
**Caution:** the `knowledge/` vs `wiki/` distinction is *curation-state* (per #43 — unreviewed vs promoted), not just legacy cruft. Confirm the promote/pending flow (#38) doesn't depend on the `knowledge/` write path before removing it. If it does, that path's removal is gated on the promote-verb work, not free.
## Acceptance
- [ ] Caller audit complete (who, if anyone, uses domain/type/knowledge-path)
- [ ] Legacy params marked deprecated in the schema
- [ ] Live callers migrated to wing/hall
- [ ] `knowledge/`-path dependency on the promote flow (#38) confirmed or ruled out before removal
- [ ] Legacy params + dead code path removed; `brain_write` has one behaviour
- [ ] `task check` green; existing brain_write/update tests still pass
## Related
- ADR-0012 (legacy-param debt) · #43 (knowledge/ vs wiki/ is curation-state, not cruft) · #38 (promote flow that may depend on knowledge/) · sibling #78 (brain_index)
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Charter: ADR-0012 ("legacy-param debt is real and in scope") · needs versioned-deprecation discipline
Problem
brain_write's schema carries legacy params from before the wing/hall model:domain,type, and theknowledge/landing path (the description literally says "(legacy)" several times). They're live API surface, so every caller has to read past them, and the two code paths (legacyknowledge/write with old frontmatter vs. wing+hallwiki/write) meanbrain_writehas two behaviours depending on which optional fields are set. That's exactly the mechanism-leak + surface-rot ADR-0012 warns about.What to do (versioned deprecation, NOT a hard break)
Per ADR-0012's migration discipline — add-new / deprecate-old / migrate-callers / then-remove:
domain/type/the knowledge/ path. Capture the real usage before changing anything.knowledge/-landing branch sobrain_writehas one behaviour.Caution: the
knowledge/vswiki/distinction is curation-state (per #43 — unreviewed vs promoted), not just legacy cruft. Confirm the promote/pending flow (#38) doesn't depend on theknowledge/write path before removing it. If it does, that path's removal is gated on the promote-verb work, not free.Acceptance
knowledge/-path dependency on the promote flow (#38) confirmed or ruled out before removalbrain_writehas one behaviourtask checkgreen; existing brain_write/update tests still passRelated