# HyperTwist Repo Intake, Retention, And Product-Fit Doctrine

Created on `2026-05-14`

## Status

This document is now the canonical HyperTwist doctrine for keeping the
following states separate:

- bookmarked
- queued
- source-read
- retained
- product-fit
- implementation-authorized
- implemented

It is operating doctrine.

It is not a casual note.

It is not packet-local wording.

It is not a temporary preference.

## Core rule

A bookmarked repo is only intake.

That means:

- a bookmarked repo is a candidate for later review
- a bookmarked repo is not an integration commitment
- a bookmarked repo is not a retained-donor decision
- a bookmarked repo is not a product-fit decision
- a bookmarked repo is not an implementation authorization
- a bookmarked repo is not proof of ownership in any product lane
- a bookmarked repo is not proof that it should survive evaluation
- a bookmarked repo is not proof that it should receive maximum realization later
- a bookmarked repo is not proof that it belongs in HyperTwist at all

HyperTwist must preserve the right to stop cleanly at any later stage.

## Anti-conflation rule

Future HyperTwist instances must not collapse the following into one vague
“good repo” judgment:

- bookmarked != retained
- retained != product-fit
- product-fit != implementation-authorized
- implementation-authorized != implemented
- source-read != approved
- queued != preferred
- compared != selected
- legally usable != strategically correct
- feature-rich != product-relevant
- technically elegant != worth integrating
- permissive != stronger donor
- restrictive != weaker donor
- harder route != weaker donor

These distinctions are mandatory.

They belong in the authority path, not only in one packet summary.

## Multi-stage decision model

Every serious repo evaluation should keep the following questions separate.

### 1. Intake question

Was the repo worth bookmarking, parking, or capturing for later review?

This is the weakest statement.

It means only:

- worth remembering
- worth revisiting
- possibly relevant later

It means nothing stronger.

### 2. Source-evidence question

Has the repo actually been read deeply enough to justify a real judgment?

Possible evidence levels include:

- no real source read yet
- shallow metadata only
- README-level read only
- selective source read
- full packet-grade source evaluation

Bookmark presence must never masquerade as evidence.

### 3. Donor-value question

Does the repo contain durable value at all?

Possible value classes include:

- architecture
- domain models
- contracts
- runtime patterns
- orchestration logic
- protocol seams
- persistence models
- UX patterns
- workflow patterns
- tests or fixtures
- observability patterns
- tooling structure
- adapter patterns
- clean-room-worthy subsystem ideas

A repo may contain no meaningful donor value.

That is an allowed conclusion.

### 4. Product-fit question

Even if a repo has donor value, does that value fit HyperTwist’s actual
product direction?

This verdict must be explicit.

A repo can be:

- impressive
- legally usable
- feature-rich
- technically strong
- architecturally interesting
- worth studying

and still not fit HyperTwist.

That is a valid result.

Donor value is not the same as product fit.

### 5. Retention question

If the repo has real value and meaningful fit, what is its retained posture?

Allowed outcomes include:

- worth later bounded integration
- donor-only for later
- reference-only
- pattern-only
- not worth integrating

These outcomes are materially different and must not be blurred.

### 6. Ownership question

If retained, what exact lane does the repo belong to?

Examples:

- primary owner of a bounded subsystem
- secondary owner inside a narrower lane
- subordinate donor under a stronger owner
- adjacent donor beside a stronger owner
- reference-only and not an owner at all

Bookmark presence must not give a repo artificial ownership weight.

### 7. Realization-depth question

If the repo later returns, what is the intended depth?

Possible outcomes:

- no implementation
- reference-only
- pattern-only
- bounded subsystem realization
- broader but still bounded realization
- full positive realization of the retained lane

Do not jump from bookmark to “must fully integrate.”

### 8. Implementation question

If retained, what exact bounded lane should it enter, at what phase, and at
what depth?

Implementation authorization must be explicit.

Planning artifacts alone are not authorization.

## Donor strength and legal posture are separate axes

HyperTwist must explicitly separate:

1. technical and product-fit ownership judgment
2. legal, compliance, and integration-route judgment

These are different axes.

A restrictive, copyleft, mixed-license, or boundary-sensitive repo can still
be:

- the technically stronger donor
- the better product fit
- the rightful owner of a bounded subsystem lane
- the repo that should displace a permissive alternative on technical grounds

Permissive status does not automatically win the ownership comparison.

Restrictive status does not automatically lose it.

What legal posture changes is the allowed route, for example:

- direct permissive incorporation
- bounded adapter
- sidecar or service boundary
- protocol boundary
- clean-room handoff
- reference-only
- pattern-only
- donor-only for later
- no integration despite technical strength

HyperTwist therefore evaluates overlapping repos in two passes:

1. decide which repo is stronger on technical, product-fit, and ownership grounds
2. decide what route the winner may use given license posture and compliance constraints

Harder route does not mean weaker donor.

It means harder route.

## Required evaluation output standard

Every serious repo evaluation should now try to state all of the following:

- exact source basis read
- licensing posture
- technical donor-strength verdict
- ownership verdict
- explicit displacement or non-displacement rationale
- integration-route verdict
- preserved subsystem ideas
- subordinate or later value
- explicit product-fit verdict
- explicit non-promotion decisions
- rationale for exclusion, demotion, or non-fit
- retention posture
- owner-lane placement
- recommended implementation phase if retained
- recommended realization depth if retained
- exact repo-level outcome category:
  - `implemented now`
  - `retained for later implementation`
  - `retained as reference only`
  - `retained only for pattern extraction`
  - `excluded`
- if retained, exact realization class:
  - `full bounded capability realization`
  - `narrower bounded slice`
- if a narrower bounded slice is chosen, the exact kept capability families
  and exact not-kept capability families
- acceptance markers if it later returns
- explicit statement of what the repo should never be mistaken for

The product-fit verdict must not be implicit.

It must be explicit.

Closeout-shape note:

- emitted packet summaries and chat closeouts must follow
  [HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md](C:/HyperTwist/docs/ops/HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md:1)
- compactness may not erase the outcome taxonomy, restrictive posture,
  clean-room boundary, donor scope, kept-versus-not-kept capability families,
  validation blockers, omission accounting, or next-sequence naming

## Approved non-fit or non-integration outcomes

HyperTwist should be able to conclude any of the following without friction:

- worth bookmarking, not worth integrating
- worth reading, not worth retaining
- technically valuable, not a product fit
- product-adjacent, but not within current scope
- weaker overlap under a stronger owner
- donor-only for later
- reference-only
- pattern-only
- interesting but strategically distracting
- valuable in theory, not worth the implementation burden
- not worth integrating at all

These are valid outcomes.

Do not force every bookmarked repo toward implementation.

## Approved rationale classes

If a bookmarked repo is later judged non-fit, non-retained, or non-integrated,
record a concrete reason.

Approved rationale classes include:

- off-topic to HyperTwist product scope
- inferior duplicate
- superseded by stronger retained owner
- weaker overlapping implementation
- host-shell glue
- commodity scaffolding
- boundary-sensitive value better kept as reference
- architecture mismatch
- workflow mismatch
- strategic non-fit
- later-horizon only
- useful pattern, but not a real donor lane
- not worth the integration cost relative to likely product gain

No vague dismissal language.

No hand-waving.

No silent downgrade.

No drift from bookmark to exclusion without rationale.

## Owner-boundary rule

A bookmarked repo must not receive special authority merely because it was
captured.

It must not displace:

- stronger retained owners
- first-party product architecture
- already-closed packet outcomes
- established subsystem boundaries
- stronger-fitting donors
- more coherent product direction

If a bookmarked repo loses an ownership comparison, record why.

If it still has residual value in a narrower lane, preserve that value there.

If it has no durable lane, say so.

## Ownership-versus-route examples

Example A:

- a permissive repo is easier to incorporate
- a restrictive repo is clearly stronger in the bounded subsystem

Correct result:

- the restrictive repo may still win ownership
- the implementation route becomes boundary-first, clean-room, sidecar, or another constrained path as required

Example B:

- a restrictive repo is impressive
- a permissive repo is still the stronger product fit and better owner

Correct result:

- the permissive repo wins
- the restrictive repo may remain reference-only, donor-only for later, or subordinate
- the restrictive repo does not lose merely because it is restrictive; it loses because it is the weaker owner here

Example C:

- a restrictive repo wins a narrow lane
- a broader permissive repo remains the stronger owner in a neighboring lane

Correct result:

- preserve the restrictive repo as the narrow owner where it is strongest
- preserve the permissive repo as the broader owner where it is stronger
- do not let route difficulty distort lane boundaries

## Failure cases to prevent

This doctrine exists to block the following failure modes:

### 1. Bookmark inflation

A repo gets bookmarked and later instances start speaking about it as if it is
already favored.

### 2. Queue inflation

A repo appears in a sequence doc and later instances start treating queue
position as a merit signal.

### 3. Evaluation inflation

A repo gets source-read and later instances assume that source-read means it
belongs in the product.

### 4. Retention inflation

A repo is retained for some bounded value and later instances start speaking as
if the full product should be integrated.

### 5. Implementation inflation

A repo is discussed often enough that later instances casually describe it as
if it already exists in product surfaces.

### 6. Permissive bias

A later instance assumes that a permissive repo should win by default over a
restrictive or boundary-sensitive repo.

### 7. Restrictive demotion by reflex

A later instance sees GPL, AGPL, mixed-license, enterprise-sliced, custom, or
boundary-sensitive posture and casually downgrades the repo's technical
ownership claim without comparing subsystem value.

### 8. Ownership-route collapse

A later instance uses legal posture to answer a technical ownership question.

### 9. Route-to-rank confusion

A later instance assumes that because a repo must route through clean-room,
sidecar, allowlist, or subtree-boundary handling, it therefore cannot be the
strongest donor.

### 10. Overcorrection

A later instance swings too far in the other direction and starts treating
restrictive repos as automatically superior or specially authoritative.

All of these are doctrine failures.

## Operational vocabulary

Use these definitions.

### Bookmarked

Captured for later review only.

### Queued

Placed into an evaluation or execution sequence only.

### Source-read

Evidence has been gathered from actual source materials.

### Retained

The repo survived evaluation as having some meaningful preserved value.

### Product-fit

The retained value actually belongs in HyperTwist’s real product direction.

### Technical owner

The repo that best owns a lane on architecture, subsystem quality, and
product-fit grounds.

### Ownership verdict

The explicit judgment about who should own the lane on technical and
product-fit grounds.

### Integration route

The allowed path for using or realizing retained value given license posture,
custody, compliance, and boundary constraints.

### Route verdict

The explicit judgment about how the winning value may enter the product, if at
all.

### Implementation-authorized

A bounded implementation lane has been explicitly approved.

### Implemented

The bounded work has actually landed in first-party product surfaces under
explicit implementation authority.

### Reference-only

Useful to study, not intended for direct donor realization.

### Pattern-only

Useful as inspiration or recurring design pattern, not as a retained donor
lane.

### Donor-only for later

Potentially useful later, but not active implementation scope now.

### Permissive route

A lower-friction incorporation path available when the repo posture allows it.

### Restrictive route

A constrained path such as clean-room, sidecar, protocol boundary,
reference-only use, pattern-only use, donor-only deferral, or explicit
non-integration.

### Not worth integrating

No later bounded implementation should be assumed from the current evaluation.

## Max-value extraction still applies

This doctrine must not make evaluation timid.

Do not interpret “bookmark is only intake” as permission to do shallow review.

If a repo is actually relevant:

- read it properly
- extract value richly
- say clearly if it deserves a bounded retained lane
- say clearly if it deserves maximum realization inside that lane

The point of this doctrine is not:

- to weaken extraction
- to flatten donors
- to become fear-driven
- to avoid hard judgments

The point is:

- to stop intake metadata from masquerading as product intent
- to preserve honest product-fit decisions
- to prevent false momentum toward implementation

## Live or product-surface scanning rule

Routine live or product-surface scanning is no longer the default evaluation
step.

Assume a repo is not implemented unless explicit implementation authority says
otherwise.

Only verify live or product-surface incorporation when the active task
specifically depends on current implementation state.

Bookmarks, queues, planning artifacts, and docs metadata are not proof of
implementation.

## Authority use

Use HyperTwist docs this way:

- this document:
  - intake doctrine
  - anti-conflation rules
  - product-fit doctrine
  - evaluation-state vocabulary
- packet docs:
  - repo-specific source evidence
  - donor-value extraction
  - product-fit verdicts
  - retention posture
  - owner-lane placement
- retained-set and routing docs:
  - next-phase entry
  - implementation authorization routing
- landed implementation packets and live-lane audit:
  - proof of implementation

## Closing rule

Future HyperTwist instances must be able to answer, for any repo:

- Was it only bookmarked?
- Was it actually source-evaluated?
- Does it contain durable donor value?
- Does that value fit the product?
- Is it retained?
- In what posture is it retained?
- Is it implementation-authorized?
- Has it actually been implemented?

If those answers are not easy to recover from the authority docs, the docs are
too weak and should be strengthened.
