Add "Explicit Contract Surface" semantic anchor

[Copilot]

Adds the proposed Explicit Contract Surface anchor — the practice of exposing only well-defined DTOs/contracts at layer boundaries, never domain entities, with explicit mapping at every seam.

Changes

• docs/anchors/explicit-contract-surface.adoc — English anchor covering: explicit API contracts, no domain entity leakage, explicit mapping, Anti-Corruption Layer, contract versioning, and dependency inversion at boundaries. Related to Clean Architecture, Hexagonal Architecture, DDD, SOLID DIP/ISP; proponents: Evans, Martin, Fowler.
• docs/anchors/explicit-contract-surface.de.adoc — German translation following the bilingual convention.
• website/public/data/anchors.json — Entry inserted alphabetically (between event-driven-architecture and fagan-inspection) with full metadata.
• skill/semantic-anchor-translator/references/catalog.md — Entry added to the Software Architecture section for agent discoverability.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Anchor Proposal]: Explicit Contract Surface</issue_title>
<issue_description>### Proposed Term

Explicit Contract Surface

Context (Optional)

Expose only well defined API models and contracts, never domain entities, with explicit mapping between layers.

Pre-submission Checklist

• I have searched existing anchors and this term is not already included
• This term refers to a well-established concept (not something I invented)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Anchor Proposal]: Explicit Contract Surface #350

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[raifdmueller]

Analysis of Proposed Anchors

Evaluated against the quality criteria: Precise, Rich, Consistent, Attributable.

Summary

PR	Anchor	Tier	Recommendation	Rationale
#354	P.A.R.A. Method	3	⚠️ Discuss	Rich and attributable (Tiago Forte), but knowledge management — not SE methodology. Extends catalog scope.
#355	PERT	2	✅ Accept	Classic estimation technique (1958), precise formula, well-established. Tier 2 is correct — useful but niche.
#356	Spec-Driven Development	3	⚠️ Discuss	Relevant to our workflow doc, but is it an established anchor or an emerging practice? Proponents listed (Swagger, Thoughtworks) are not the originators of the term.
#357	Explicit Contract Surface	3	❌ Reject	Not an established term — it's a combination of existing patterns (ACL, DTOs, contract-first). Proponents listed (Evans, Martin, Fowler) didn't coin this term. Fails "Attributable" criterion.
#358	Vertical Slice Architecture	3	✅ Accept	Well-established (Jimmy Bogard), precise, rich. Tier 3 is justified — complements Clean/Hexagonal Architecture.
#359	GRASP	3	✅ Accept	Classic OO patterns (Craig Larman), 9 well-defined patterns. Tier 3 justified — foundational, widely taught.
#360	KISS	1	⚠️ Discuss	Tier 1 is correctly assigned by Copilot! KISS lacks definition depth — "keep it simple" is a directive, not a methodology. Same problem as YAGNI (also Tier 1). But it's so widely referenced that excluding it feels wrong.

Detailed Analysis

#354 P.A.R.A. Method — ⚠️ Discuss

• Precise: Yes — four clear categories (Projects, Areas, Resources, Archive)
• Rich: Moderate — primarily an organizational framework, less rich than Diataxis
• Consistent: Yes — well-defined by Forte
• Attributable: Yes — Tiago Forte, "Building a Second Brain"
• Concern: Extends catalog beyond SE into personal productivity. Is that in scope?

#355 PERT — ✅ Accept

• Precise: Very — concrete formula (O+4M+P)/6, network diagrams, critical path
• Rich: Yes — connects estimation, scheduling, probability, risk
• Consistent: Yes — 65+ years of established usage
• Attributable: Yes — Malcolm, Roseboom, Clark, Fazar (1958)
• Tier 2 correct: Useful but specialized (project planning, not daily coding)

#356 Spec-Driven Development — ⚠️ Discuss

• Precise: Moderate — the term is used differently by different people (API-first vs. formal specs vs. our workflow doc)
• Rich: Yes — connects to BDD, TDD, contract-first, verification
• Consistent: Weak — no single canonical definition
• Attributable: Weak — Swagger/Thoughtworks are not the originators; the term is emergent
• Concern: We have a whole workflow document about this. Making it an anchor could create circular references. Also, our evaluation showed EARS (similar domain) scores poorly.

#357 Explicit Contract Surface — ❌ Reject

• Precise: Moderate — describes a pattern but the name is not established
• Rich: Yes — connects ACL, DTOs, mapping, DIP
• Consistent: No — this is not a recognized term in the literature
• Attributable: No — Evans/Martin/Fowler did not coin this term
• This is a design practice, not a semantic anchor. It combines existing anchors (Clean Architecture, DDD, SOLID DIP) but doesn't add a new activation.

#358 Vertical Slice Architecture — ✅ Accept

• Precise: Yes — clear distinction from layered architecture
• Rich: Yes — connects to CQRS, feature cohesion, screaming architecture
• Consistent: Yes — Jimmy Bogard's talks and blog posts are canonical
• Attributable: Yes — Jimmy Bogard
• Tier 3 justified: A well-known alternative to Clean/Hexagonal that LLMs should know

#359 GRASP — ✅ Accept

• Precise: Very — 9 named patterns with clear definitions
• Rich: Yes — foundational OO design patterns, connects to SOLID, GoF
• Consistent: Yes — Craig Larman's "Applying UML and Patterns" is canonical
• Attributable: Yes — Craig Larman
• Tier 3 justified: Standard curriculum material, widely taught

#360 KISS — ⚠️ Discuss

• Precise: Low — "keep it simple" is a directive, not a methodology
• Rich: Low — doesn't activate multiple interconnected concepts
• Consistent: Mixed — everyone agrees on the principle but not on what "simple" means
• Attributable: Yes — Kelly Johnson (Lockheed Skunk Works)
• Tier 1 correctly assigned: Same tier as YAGNI and TIMTOWTDI. Copilot got this right!
• Question: We reference KISS in the workflow doc (AGENTS.md conventions). Rejecting it would be inconsistent.

[raifdmueller]

Thanks for this proposal! The described practice — exposing only DTOs at boundaries, never domain entities, with explicit mapping — is genuinely valuable and well-articulated.

Recommendation: don't merge as a semantic anchor.

The core issue is that "Explicit Contract Surface" is not an established term in the software engineering literature. Here's how it compares to our quality criteria:

• Precise ✓ — the practice is well-defined
• Rich ✓ — connects to ACL, DTOs, DIP, contract-first design
• Consistent ✗ — the term is not recognized; searching for it returns no canonical results
• Attributable ✗ — Evans, Martin, and Fowler are listed as proponents, but they didn't coin this term. They coined the underlying concepts (Anti-Corruption Layer, Dependency Inversion, etc.)

This is a design practice described using existing anchors, not a new semantic anchor itself. The same behavior is activated by prompting:

"Use Clean Architecture with an Anti-Corruption Layer. Expose only DTOs at boundaries."

That prompt uses three established anchors (Clean Architecture, ACL, DTO) and achieves the same result.

We'd love to see this as a blog post or a pattern description in the workflow documentation! It's a well-articulated practice — it just doesn't meet the bar for a standalone semantic anchor.

[raifdmueller]

This concept has been incorporated into #364 (Semantic Contracts) as the "Layer Boundaries" contract:

At every layer boundary:

• Expose only well-defined DTOs and contracts — never domain entities
• Use explicit mapping at every seam
• Apply Anti-Corruption Layers when integrating external systems

Referenced anchors: Clean Architecture, Hexagonal Architecture, DDD, SOLID (DIP, ISP)

The practice is valuable — it just works better as a team convention (Semantic Contract) that users can select and download, rather than as a standalone anchor in the catalog. This way teams can customize it for their project and the contract references the established anchors that back it up.