# Standard Enhancement Proposal (SEP) Template

Copy this template when proposing a change to the Vinculum Standard. Fill in each section; if a section doesn't apply, briefly note why (e.g., "N/A" for backwards compatibility if this is a new feature).

---

## Title

_A short, descriptive title for your proposal. e.g., "Add optional timeout parameter to tool invocation"_

## Author

_Your name, email, and/or GitHub handle_

## Status

_One of: Draft, Discussion, Accepted, Implemented, Superseded, Rejected_

_Use "Draft" when you first open the proposal. Move to "Discussion" when you're ready for community feedback._

## Type

_What kind of proposal is this?_

- **Entry Shape**: Changes to the entry schema itself (required/SHOULD/MAY fields)
- **Operation**: New or changed read/write/supersede/reason-on semantics
- **Conformance**: New or changed conformance criteria for implementations
- **Convention**: Best practices or interoperability conventions built on top of the Standard
- **Documentation**: Clarifications or additions to the spec text itself

## Created

_Date you opened this proposal. Format: YYYY-MM-DD_

## Abstract

_One or two sentences summarizing the proposal. A reader should understand what you're proposing and why after reading this._

---

## Motivation

**Problem**: What gap or pain point does the Standard currently have? Describe the issue clearly.

**Why now**: Is this a new use case, a missing piece, or a fix for a bug? What context makes this proposal timely?

**Impact**: Who benefits from this change? How many implementations or users would be affected?

---

## Specification

This is the meat of your proposal. Describe the new behavior, format, or convention precisely:

- **What changes**: Which section(s) of the Standard does this touch?
- **New behavior**: Exactly what is being added or modified? Use code blocks, tables, or diagrams if helpful.
- **Examples**: Show a concrete example of the new feature in action. Before/after if it's a change.
- **Edge cases**: What happens at boundaries? What is explicitly NOT supported?

---

## Rationale

**Design choices**: Why this approach over alternatives? Name at least one alternative you considered and explain why you didn't choose it.

**Tradeoffs**: What are the costs? Complexity? Performance? Backwards compatibility? Call out any risks.

**Precedent**: Have other standards (PEP, RFC, OpenAPI, etc.) solved similar problems? What did they do, and should we follow their pattern?

---

## Backwards Compatibility

- **Breaking change?** Yes / No
- **If yes**: Provide a migration path. How do existing implementations adopt this change? Can they do it gradually?
- **If no**: Will old implementations ignore this gracefully, or do they need code changes to stay compatible?

---

## Security Implications

- Are there any security considerations? (e.g., new fields that could leak sensitive data, new attack vectors, authentication changes)
- If this proposal changes how tools are invoked or how resources are served, does it introduce new risks?
- If there are risks, how are they mitigated?

---

## Copyright

_License statement for this proposal. Example: "This proposal is released into the public domain."_

---

## Discussion

_Link to the issue tracker or discussion thread where community feedback is happening._

---

## Notes for Authors

- **Be specific**: Vague language ("make it better", "improve compatibility") will slow down review. Concrete examples and exact wording are better.
- **Acknowledge complexity**: If your proposal has edge cases or requires careful implementation, say so. Reviewers prefer honesty.
- **Iterate openly**: It's okay to revise your proposal based on feedback. Update the Status section and note what changed.
- **Expect questions**: Reviewers will ask "why" a lot. That's healthy. Detailed answers here mean faster adoption later.

---

## Example Sections

### If proposing a new entry field:

```
## Specification

### Field: `foo`

A new optional field on the entry shape, for [use case]. Implementations MUST:
- Accept `foo` (string, optional) without rejecting entries that omit it
- Preserve `foo` across supersession (the new entry MAY carry it forward)

Implementations MAY:
- [optional behavior]

## Example

```json
{
  "id": "3fa1...e2",
  "type": "decision",
  "content": "...",
  "author": "example",
  "created_at": "2026-07-10T00:00:00Z",
  "foo": "baz"
}
```
```

### If proposing a convention:

```
## Specification

### Naming Convention for [thing]

All [things] MUST be named using [pattern]. For example:
- ✅ `valid_name_here`
- ❌ `InvalidNameHere`

Rationale: [Why this pattern?]
```

---

_This template is based on the structure of PEP (Python Enhancement Proposals) and RFC (Request for Comments). Use it as a starting point; adjust sections if needed to fit your proposal._