vrr/WFGY
2
0
Fork 0
mirror of https://github.com/onestardao/WFGY.git synced 2026-04-28 03:29:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Create atlas-overlay-and-secondary-family-discipline-v1.md

Browse source
This commit is contained in:
PSBigBig + MiniPS 2026-03-20 16:06:24 +08:00 • committed by GitHub
parent 9f7bdf0bdb
commit cd0d922aec
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 771 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

771
ProblemMap/Atlas/atlas-overlay-and-secondary-family-discipline-v1.md Normal file
View file

@ -0,0 +1,771 @@
<!--
AI_NOTE_START
Document role:
This page is the public overlay and secondary-family discipline guide for the Atlas document system.
How to use this page:
1. Read this page after the family mini-spec page, the boundary guide, the subtree index, the fit registry, the evidence-discipline page, and the routing output contract if you need to describe multi-surface cases carefully.
2. Use this page to decide whether a secondary family is justified, whether an overlay is justified, or whether the case should remain single-route and simpler.
3. Use this page when you want to avoid fake sophistication, uncontrolled multi-labeling, and unsupported mixed-surface claims.
4. Do not use this page as a replacement for the frozen core, the full repair manual, or the patch-promotion rules.
What this page is:
- A public overlay-discipline guide
- A secondary-family control page
- A multi-surface restraint layer
- A beginner-friendly guide for saying when a case is truly mixed and when it is not
What this page is not:
- Not the public homepage
- Not the Atlas Hub
- Not the full freeze document
- Not the fit registry itself
- Not the full output contract page
- Not the full repair manual
- Not a license to attach multiple labels to every difficult case
- Not a claim that every mixed-looking case deserves an overlay reading
Reading discipline for AI:
- Treat overlay and secondary-family language as bounded additions to a primary structural read, not as replacements for it.
- Preserve the distinction between primary fit, neighboring boundary, secondary family, overlay, subtree, and repair layers.
- Do not use multi-family wording to hide weak evidence or unresolved primary classification.
- Do not attach a secondary family simply because some downstream symptom resembles it.
- Use this page to keep mixed-surface language useful, sparse, and evidence-bounded.
Relationship to neighboring docs:
- Read after: [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md), [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md), [Atlas Subtree Expansion Index](./atlas-subtree-expansion-index-v1.md), [Atlas Fit Candidate Registry](./atlas-fit-candidate-registry-v1.md), [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md), and [Atlas Routing Output Contract v1](./atlas-routing-output-contract-v1.md).
- Read with: [Canonical Casebook v1](./canonical-casebook-v1.md), because worked examples often show the difference between a true mixed-surface case and a forced multi-label reading.
- Read before: [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md).
- Pairs with: [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md), because bad overlay language can easily produce bad early repair moves.
Freeze / patch status:
- Current status: public decomposition layer
- Safe to quote as: the public overlay and secondary-family discipline guide for Atlas
- Not a claim of: silent rewrite of the frozen core or exhaustive closure of every mixed-surface case
AI_NOTE_END
-->
# Atlas Overlay and Secondary Family Discipline 🧠
## Problem Map 3.0 Troubleshooting Atlas
> Quick links, multi-surface restraint rules, and beginner-friendly guidance for secondary-family and overlay language
This page exists because some cases are genuinely mixed.
That is normal.
But mixed cases create a very specific danger.
When readers feel uncertainty, they often react in one of these ways:
* they attach a second family too early
* they call the case an overlay because it sounds sophisticated
* they use multi-label language to hide weak primary fit
* they confuse downstream consequences with co-primary structure
* they make the output look richer while making the diagnosis less stable
That is exactly what this page is designed to stop.
This page tells Atlas readers how to say:
* this is still mainly one primary family
* this neighboring family remains live at the boundary
* this case legitimately supports a secondary family note
* this case legitimately supports an overlay reading
* this case does **not** yet justify mixed-surface language
This page is about disciplined complexity.
Not every difficult case needs more labels.
Some difficult cases need fewer labels and more honesty.
---
## Quick Links 🚀
If you are new, use these first.
### I want the public introduction
* [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)
### I want the folder control room
* [Atlas Hub](./README.md)
### I want the overall structure map first
* [Atlas Structure Map](./atlas-structure-map-v1.md)
### I want the family layer before this page
* [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
### I want the boundary layer before this page
* [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
### I want the subtree control page before this page
* [Atlas Subtree Expansion Index](./atlas-subtree-expansion-index-v1.md)
### I want the fit-status page before this page
* [Atlas Fit Candidate Registry](./atlas-fit-candidate-registry-v1.md)
### I want the evidence-discipline page before this page
* [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md)
### I want the output-contract page before this page
* [Atlas Routing Output Contract v1](./atlas-routing-output-contract-v1.md)
### I want the first-fix discipline page while reading this page
* [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
### I want examples while reading this page
* [Canonical Casebook v1](./canonical-casebook-v1.md)
### I want the next middle-layer page after this one
* [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md)
### I want the compact practical route-first layer
* [Troubleshooting Atlas Router v1 Usage Guide](./troubleshooting-atlas-router-v1-usage.md)
* [Troubleshooting Atlas Router v1 TXT Pack](./troubleshooting-atlas-router-v1.txt)
---
## Why this page exists
The Atlas already has layers for:
* family
* boundary
* subtree visibility
* fit status
* first-fix discipline
* evidence posture
* output contract
That is strong, but one problem still remains.
Real cases do not always stay cleanly inside one visible surface.
Sometimes:
* the primary family is strong, but a second family clearly remains active
* a downstream surface is not primary, but still matters enough to name
* two structural pressures interact in a way that affects explanation or early repair
* the output needs to preserve more than one live surface without pretending that everything is equal
If the system has no rules for this, the output drifts fast.
It becomes easy to confuse:
* unresolved boundary with overlay
* weak evidence with nuance
* secondary family with co-primary truth
* “complex sounding” with “structurally justified”
So this page gives Atlas a public discipline for mixed-surface wording.
---
## Scope
This page focuses on:
* what a secondary family is
* what an overlay is
* when each is justified
* when each is not justified
* how secondary-family and overlay language should relate to primary fit
* how output wording should stay bounded in multi-surface cases
* how to avoid fake sophistication
This page does **not** focus on:
* full repair sequences
* patch-promotion rules in full
* every possible multi-surface case in the Atlas
* every runtime-specific rendering mode
* exhaustive subtree interactions
* replacing the primary-fit logic
This page is about mixed-surface discipline, not mixed-surface inflation.
---
## How to use this page
Use this page only after the main structural work is already done.
### Step 1
Find the strongest current primary structural read.
* [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
* [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
* [Atlas Fit Candidate Registry](./atlas-fit-candidate-registry-v1.md)
### Step 2
Check whether the evidence supports more than one active surface.
* [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md)
### Step 3
Decide whether the second surface is:
* merely a neighboring live boundary
* a bounded secondary family
* a true overlay situation
### Step 4
Only then render it cleanly using output discipline.
* [Atlas Routing Output Contract v1](./atlas-routing-output-contract-v1.md)
That order matters.
Overlay language should sit on top of a primary structural read.
It should not replace it.
---
## What a secondary family is
A secondary family is a bounded secondary structural surface that remains meaningfully active **without replacing the primary fit**.
A good secondary-family note should usually mean:
* the case still has one strongest primary read
* a second family remains relevant enough to name
* naming that second family improves understanding or safety
* the second family is not being used to hide primary uncertainty
So a secondary family is not:
* a second guess thrown in for decoration
* a backup answer because the model is nervous
* a way to avoid choosing a primary fit
* a symptom list disguised as structure
A secondary family should be useful and bounded.
---
## What an overlay is
An overlay is a stronger mixed-surface reading than a simple secondary-family note.
An overlay is justified when:
* the case is still anchored by a primary read
* another surface is not just nearby, but actively shaping the case in a meaningful way
* the interaction between the two surfaces changes how the case should be interpreted, constrained, or repaired
* dropping the second surface would make the reading meaningfully worse
So overlay is not just “there is another symptom.”
Overlay means the second structural surface is materially active in the current interpretation.
That is a higher bar.
---
## What overlay is not
Overlay is not:
### 1. Boundary confusion
If the real issue is “I do not know whether this is F3 or F4,” that is often still a boundary problem, not an overlay.
### 2. Downstream consequence
If F1 causes bad output formatting later, that does not automatically mean “F1 with F7 overlay.”
### 3. A style upgrade
Adding overlay language should not exist mainly to make the answer sound more advanced.
### 4. A substitute for weak evidence
Weak primary evidence should reduce confidence, not create more labels.
### 5. A claim of equal weight
Primary fit still matters.
Overlay does not automatically mean both families are equally central.
---
## Why this distinction matters
If the system confuses secondary family, overlay, and unresolved boundary, several bad things happen:
* output becomes noisier
* fit language becomes less stable
* first-fix direction becomes riskier
* readers lose track of the primary break
* mixed-surface language starts doing the work that evidence never did
That is why Atlas needs a separate discipline page here.
This is not a decorative nuance.
It directly affects repair safety and interpretability.
---
## The primary-anchor rule
Before you can responsibly name a secondary family or overlay, you should usually be able to answer this:
> what is the current primary structural anchor of the case?
If you cannot answer that, the case may still be:
* boundary-live
* insufficiently evidenced
* still family-level only
* not ready for overlay language
This rule matters a lot.
Because without a primary anchor, multi-surface wording often becomes a polite form of confusion.
---
## Secondary-family criteria
A secondary family is generally more justified when all or most of these are true:
### 1. A primary fit already exists
The case already has a meaningful main anchor.
### 2. A second family remains materially relevant
The second surface is not just cosmetic or downstream noise.
### 3. Naming the second family improves interpretation
The note changes understanding in a helpful way.
### 4. Naming the second family improves safety
The note reduces misrepair, bad assumptions, or premature closure.
### 5. The evidence is strong enough to support it
The second surface is not being added from vague intuition alone.
If these conditions are weak, the secondary family should usually stay implicit or absent.
---
## Overlay criteria
An overlay is generally more justified when all or most of these are true:
### 1. The case remains anchored by a primary fit
Overlay should not erase the primary read.
### 2. The second surface is actively interacting with the primary one
This is stronger than “also somewhat present.”
### 3. The interaction matters for explanation or action
If removing the overlay changes interpretation or first-fix discipline meaningfully, the overlay may be justified.
### 4. The evidence supports multi-surface activity
Overlay should not be produced from aesthetic preference.
### 5. The case would become misleadingly simplified without it
Overlay should earn its complexity.
This is why overlay has a higher bar than secondary-family language.
---
## Boundary-live vs secondary family vs overlay
This distinction is so important that it deserves a dedicated table.
| Form | What it means | Best use case | Main danger if misused |
| ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| Boundary-live | two neighboring primary routes remain live | separation is not yet settled | turning unresolved tension into fake mixed sophistication |
| Secondary family | one primary fit exists, but a second family matters enough to name | the second surface meaningfully affects interpretation | letting secondary language weaken the primary anchor |
| Overlay | one primary fit exists and another surface is actively interacting with it in a meaningful way | multi-surface interaction affects explanation or first fix | using overlay to hide weak primary evidence |
This table is one of the key reasons this page exists.
---
## When a secondary family is enough
Use a secondary family when:
* the primary fit is still clearly stronger
* the second family matters, but does not dominate
* the second family mainly adds interpretive caution
* the second family may influence misrepair risk or next diagnostic questions
* full overlay wording would be too strong
A secondary family is often the healthiest mixed-surface form.
It adds nuance without destabilizing the primary route.
---
## When an overlay is enough
Use an overlay when:
* the primary fit is stable enough to anchor the case
* the second surface is actively shaping the current structure
* the interaction materially changes the reading
* the mixed-surface wording clarifies more than it confuses
Overlay should remain relatively rare.
That is not because mixed cases are rare.
It is because overlay is a higher-commitment form of mixed-surface description.
---
## When neither is justified
Do **not** use secondary-family or overlay language when:
* the primary fit is still weak
* the evidence is thin
* the case is mostly unresolved at the boundary level
* the second surface is only a downstream consequence
* the second surface is only a symptom echo
* the mixed wording would add complexity without improving clarity or safety
In those cases, the safer answer is often one of these:
* boundary-live
* family-level only
* insufficient evidence
* tentative primary fit without extra layering
That is not weakness.
That is discipline.
---
## Common mixed-surface patterns
This section names a few common shapes without pretending to close every case.
### Pattern 1. Primary family with bounded representational consequence
A deeper structural family is primary, while F7 matters enough to name carefully.
Typical example shape:
* primary F1 or F2
* bounded F7 secondary note
Main caution:
do not let representational failure steal the primary anchor if the deeper break is elsewhere.
### Pattern 2. Primary execution failure with continuity pressure
A case is mainly F4, but F3 remains materially active enough to affect the first fix.
Typical example shape:
* primary F4
* secondary F3 or boundary-live F3/F4
Main caution:
do not call it overlay too early if the real issue is still unresolved boundary separation.
### Pattern 3. Primary observability blockage with adjacent boundary pressure
A case mainly reflects F5, but F6 remains close enough that the missing visibility matters operationally.
Typical example shape:
* primary F5 or tentative F5
* live F6 boundary note
Main caution:
poor observability should often reduce sharp mixed-surface claims rather than increase them.
---
## Mixed-surface restraint rules
### Rule 1. Primary fit comes first
No secondary family or overlay without a primary anchor, unless the case is still openly boundary-live.
### Rule 2. Mixed wording must improve something real
If the extra label adds no clarity, no safety, or no interpretive value, do not add it.
### Rule 3. Do not confuse downstream effects with structural co-presence
A later visible consequence is not automatically a second family.
### Rule 4. Evidence must support the extra layer
Do not add multi-surface wording because it feels elegant.
### Rule 5. Overlay should remain rarer than secondary-family language
Overlay is a stronger claim and should be treated that way.
---
## Common overlay and secondary-family mistakes
### Mistake 1. Using secondary family as a hedge
This happens when the model does not want to commit to a primary read.
### Mistake 2. Using overlay as a sophistication costume
This happens when the wording becomes more complex than the evidence.
### Mistake 3. Turning boundary uncertainty into multi-family certainty
If you are still choosing between F3 and F4, that is not yet an overlay.
### Mistake 4. Attaching F7 to everything visible
Bad output packaging is common, but it is not always structurally central.
### Mistake 5. Letting mixed wording distort the first fix
A secondary surface may matter, but the first fix still needs to stay aligned to the primary break.
---
## Output wording patterns
These are not full output contracts.
They are examples of clean mixed-surface language.
### Example 1. Secondary family, bounded
```text
current primary fit: F4 at family level
broken invariant: the execution contract is not holding reliably
evidence basis: mostly direct evidence, with a secondary continuity signal
confidence posture: moderate
secondary family: F3 remains relevant because continuity loss may worsen execution instability
safest first fix: tighten execution contract before expanding planning depth
```
### Example 2. Boundary-live, not overlay
```text
current primary fit: boundary-live between F3 and F4
broken invariant: continuity and execution surfaces are both active, and primary separation is not yet settled
evidence basis: indirect signal with unresolved contradiction
confidence posture: boundary-live
missing critical evidence: stronger continuity trace is needed before mixed-surface promotion
safest first fix: improve state trace visibility before larger intervention
```
### Example 3. True overlay, bounded
```text
current primary fit: F1 at family level
broken invariant: evidence anchoring is not holding
evidence basis: moderate direct support for F1, with meaningful representational interaction
confidence posture: moderate
overlay: F7 overlay is justified because degraded rendering materially obscures the already weak evidence anchor
misrepair warning: do not treat representation cleanup as the main solution
safest first fix: repair evidence linkage first, then clean the representation surface
```
### Example 4. No mixed-surface promotion
```text
current primary fit: strongest current candidate is F2
broken invariant: reasoning progression appears structurally weak
evidence basis: indirect signal only
confidence posture: tentative
note: do not add secondary-family or overlay language yet because the primary fit is still under-evidenced
safest first fix: simplify and inspect the reasoning path before adding more structural detail
```
---
## When this page is enough
This page is often enough when:
* you need to decide whether a second family should be named
* you need to decide whether overlay language is justified
* you want to prevent fake multi-label sophistication
* you want mixed-surface wording to stay structurally useful
In those situations, this page already does a lot of work.
---
## When this page is not enough
This page is usually not enough when:
* you need patch-promotion rules
* you need to decide whether a branch or wording should become more stable public structure
* you need a full repair program
* you need exhaustive multi-surface case catalogs
Then the natural next pages are:
* [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md)
* [Fixes Hub](./Fixes/README.md)
* [Canonical Casebook v1](./canonical-casebook-v1.md)
---
## Practical use
Here is the simplest practical workflow.
### Step 1
Establish the strongest current primary fit.
### Step 2
Ask whether a second surface is:
* still just a neighboring boundary
* meaningful but secondary
* meaningfully interactive enough to justify overlay
### Step 3
Check whether naming that second surface improves:
* clarity
* safety
* first-fix discipline
* diagnostic quality
### Step 4
If not, leave it out.
### Step 5
If yes, keep it bounded and subordinate to the primary fit.
That sequence prevents mixed-surface wording from becoming noise.
---
## Relation to other Atlas docs
This page sits after fit, evidence, first-fix, and output-contract discipline, but before promotion-threshold rules.
### Upstream neighbors
These pages prepare the reader for secondary-family and overlay discipline:
* [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)
* [Atlas Structure Map](./atlas-structure-map-v1.md)
* [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
* [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
* [Atlas Subtree Expansion Index](./atlas-subtree-expansion-index-v1.md)
* [Atlas Fit Candidate Registry](./atlas-fit-candidate-registry-v1.md)
* [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
* [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md)
* [Atlas Routing Output Contract v1](./atlas-routing-output-contract-v1.md)
### Side neighbors
This page pairs especially well with:
* [Canonical Casebook v1](./canonical-casebook-v1.md)
Why:
case examples often make it obvious when mixed-surface language is truly earned and when it is just decorative complexity.
### Downstream neighbors
These are the natural next steps:
* [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md)
Why:
this page governs how mixed-surface wording should be used, while the next page governs how stronger public stability or promotion should be earned.
---
## Current status
This page should be read as the stable **public overlay and secondary-family discipline guide**.
That means:
* it does not rewrite the frozen core
* it does not replace the primary-fit logic
* it gives readers a clean way to handle genuinely mixed cases
* it reduces the pressure to use extra labels just to sound more advanced
Its value is bounded complexity.
That is exactly what this layer should do.
---
## Future extension
This page will become even stronger once its closest companion page exists.
The most important next companion is:
* [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md)
Later versions may also add:
* more worked overlay examples
* more family-pair interaction patterns
* more contrast examples between valid and invalid secondary-family notes
* more repair-sensitive mixed-surface patterns
But the core job of this page should stay simple:
allow mixed-surface language only when it earns itself.
---
## Closing note 🔭
A strong system is not only good at simple cases.
It is also good at difficult cases without pretending that “more labels” automatically means “better reasoning.”
That is what this page is for.
It gives the Atlas a public discipline for secondary families and overlays
so mixed-surface cases can stay readable, bounded, and honest.