Asset registry

Approved Asset schema, relationship model, and reuse-evidence contract for M1 (D-02 / G7). Physical Notion store is the Assets database in state-model.md. Ownership remains in the authority model.

Schema version: asset-registry.v2 (proposed; Gate B pending)
Physical realization: state-model.md revision state-model.v2
Tracking: hector-sanchez-eu/conductor#3
Brief: M1 brief

Gate B approval must name this exact revision (asset-registry.v2) together with the evaluator behavior in service/conductor/integrations/read_adapters/reuse.py.

Purpose

Before authorizing substantial new software work, Conductor must determine whether an existing system can satisfy the need (reuse), should be extended (extend), is materially different (new), or cannot be judged (insufficient-context).

Assets are enduring systems. Initiatives are work that creates or changes outcomes. An Asset may be linked to many Initiatives over time.

Identity

Field	Requirement	Meaning
asset_id	Always	Stable Conductor ID (asset.<ulid>), minted by identity allocator, persisted by executing agent for Portfolio Manager
Name	Always	Primary display name
Aliases	Optional	Former names, marketing names, folder slugs
Notion page ID	Adapter only	Locator; never replaces asset_id
Repository URL(s)	Optional	GitHub or other remotes; an Asset may have zero, one, or many
Local path	Never sufficient alone	A path on one computer is not estate identity

Local-only and multi-repo systems

• No GitHub repo: Allowed. Require a portable canonical reference (Notion Asset record + verified URL, package identity, or explicit portability_gap).
• Multiple repositories: One Asset with a list of repos and roles (e.g. frontend, api, infra).
• Multiple deployments: One Asset with environment/URL rows; do not invent one Asset per hostname unless they are independently lifecycled systems.

Physical Notion realization

Authoritative physical stores (state-model.v2):

• Asset core fields on the Assets database
• asset_repositories / asset_environments child DBs
• asset_evidence — one row per provenance/verification/promotion reference (lossless; no ordered parallel fields)
• asset_relationships — one row per typed edge with per-edge review_status, reviewer, timestamp, and evidence links
• Decisions/Events.related_assets for Asset-linked verification/promotion events

Evaluator mapping: service/conductor/integrations/read_adapters/physical.py.

Field model

Field	Required when	Purpose
asset_id	Always	Stable identity
schema_version	Always	Physical layout: state-model.v2 (see state-model.md)
asset_registry_version	Always	Asset contract: asset-registry.v2
review_status	Always	candidate reviewed rejected superseded-record
Name / aliases	Always	Discovery
purpose	Reviewed	Why the Asset exists
users_needs	Reviewed	Who it serves and what problem it addresses
capabilities	Reviewed	Comparable capability bullets (not stack slogans)
lifecycle_status	Always	proposed prototype active maintained superseded archived
estate	Always	Org vocabulary: prototype lab portfolio-org (see organization-profile.md)
repositories	When known	List of remotes + optional role
environments_urls	When known	Verified instances
stack_deploy_shape	When known	Technical comparison aids; never sole equivalence evidence
related_initiatives	When known	Links
relationships	When known	See relationship model
privacy_class	Always	Permission filter input
provenance	Always	Sources used (GitHub, Notion, deploy, human)
last_verified_at	Reviewed	Freshness
verification_evidence	Reviewed	Links/notes supporting last verification
extraction_notes	Candidate	Unreviewed AI or script extraction; never authoritative
portability_gap	When no portable canonical ref	Explicit gap text

Capability descriptions matter more than names or stacks. Two Assets may share a stack and still serve different needs; three real-estate applications may use different technologies while solving substantially the same user need.

Relationship model

Relationships are first-class and human-reviewed when they assert equivalence or replacement.

Kind	Meaning	Human review required?
related	Soft association	No (candidate ok)
depends_on	Runtime or build dependency	Prefer human for reviewed Assets
fork_of	Derived codebase	Yes before reviewed
duplicate_of	Same system under two IDs	Always human before merge
replaces / replaced_by	Supersession	Always human
extends	Intended base for future work	Yes before using as extend evidence

Automated extraction may create candidate relationships. It must not silently merge Assets or mark extracted descriptions authoritative.

Review status and promotion

text candidate ──human review──► reviewed │ ├──rejected (not an Asset / out of scope) └──superseded-record (ID retained; points at survivor)

Status	May influence reuse/extend/new?	May override README/index?
candidate	Only as insufficient-context or weak hint with explicit caveat	No
reviewed	Yes	Yes (Notion Asset wins over README/index)
rejected	No	No
superseded-record	Cite survivor only	Survivor wins

Candidate → reviewed checklist

1. Stable asset_id persisted.
2. Purpose, users/needs, and capabilities filled in comparable terms.
3. Lifecycle, estate, privacy set.
4. Provenance and last_verified_at recorded.
5. Duplicate/fork/replace groups resolved or explicitly open.
6. Local-only Assets have portable canonical reference or portability_gap.
7. Human reviewer recorded on the promotion Decision/Event or Asset provenance note.

Reuse decision evidence contract

Preparation or conversation tools that answer estate overlap must return exactly one of:

Result	Meaning	Minimum evidence
reuse	Existing capability already satisfies the need	Validated EstateComparison + opaque ExhaustiveSnapshot; exactly one positive claim in the comparison payload; no_material_gaps with bound evidence; privacy/runtime compatible
extend	An existing Asset is the best base; delta justified	Validated EstateComparison with extend payload; physical extends edge matching need/delta; opaque snapshot
new	No existing Asset sufficiently fits	Validated EstateComparison with exhaustive negatives + ruled-out dispositions; opaque ExhaustiveSnapshot.is_exhaustive
insufficient-context	Estate or requirement evidence too weak	Missing/invalid comparison, non-exhaustive snapshot, physical batch defects, or incompatible constraints

Authority boundary (EstateComparison architecture)

1. Raw caller dictionaries (search_coverage_json claims/dispositions/Booleans) never authorize reuse / extend / new.
2. The decisive semantic payload lives only in an authoritative Decisions/Events comparison_payload parsed into a frozen EstateComparison.
3. Exhaustiveness is an opaque adapter-produced ExhaustiveSnapshot (factory + seal). A Boolean or coverage-dict field cannot forge it.
4. Changing caller fields without changing the authoritative comparison/snapshot must not change a decisive outcome.
5. Without both a need-matching EstateComparison and an exhaustive snapshot, return only insufficient-context.
6. The runtime trust boundary is serialized MCP input versus trusted in-process adapter code. Direct dataclass construction is never issued and fails closed; parser/validator/factory functions are internal adapter APIs, not security isolation from malicious code already executing inside the Conductor process.
7. The snapshot is bound to the exact validated physical-batch digest, mapped-estate digest, comparison digest, asserted need, source completeness, and snapshot version. Substituting Assets or a comparison after validation fails closed.

Supporting rules

1. new is invalid merely because the requesting agent did not know another project existed.
2. Do not infer Asset equivalence from repository name, stack, embeddings, or lexical similarity alone.
3. Unreviewed extraction cannot authorize reuse or extend.
4. Claim citations must match mapped Asset provenance/verification tokens.
5. extend requires a fully reviewed physical extends edge (direction/reviewer/timestamp/resolved evidence/asserted_need/asserted_delta).
6. Unsupported review_status values and duplicate asset_id rows fail closed.
7. Physical batch validation (including repos/envs/orphans) must pass before mapping; defects block exhaustiveness.
8. Comparison event_class is restricted to estate-comparison / portfolio-disposition.

The evaluator in service/conductor/integrations/read_adapters/reuse.py consumes typed records from estate_comparison.py only.

Comparison dimensions (guidance)

Use as evidence axes, not automatic scores:

• Purpose and users/needs
• Capabilities (functional)
• Privacy / tenancy constraints
• Lifecycle and estate class
• Deployment/runtime constraints
• Relationship to active Initiatives

Representative golden-path requirement

M1 proves estate discovery through source coverage, not a manually supplied list of applications. After Gate C enumeration, select at least one representative application—preferably real estate—or a materially related group and create comparable, evidence-backed Asset candidates for it.

The golden-path analysis must cover purpose, users/needs, capabilities, lifecycle, estate, provenance, freshness, privacy, repositories, deployments, and material relationships. A descriptive count or remembered application name is not evidence of estate completeness. Incomplete or unavailable source coverage must remain explicit and force insufficient-context where it affects a decision.

Conflict rules

1. Reviewed Notion Asset wins over README, local folder names, and estate index cache.
2. GitHub wins for source and delivery evidence, not for purpose/need narrative.
3. Candidate extraction never silently overwrites reviewed fields.
4. Duplicate merge requires human approval; keep superseded asset_id as superseded-record pointing at the survivor.

Gate B approval checklist

Hector approves Gate B when commenting Conductor-Gate-B: approve on issue #3 naming revision asset-registry.v2, accepting:

1. Identity and local-only / multi-repo rules.
2. Field model and review_status promotion flow (physical SoR via state-model.v2).
3. Relationship kinds as per-edge asset_relationships rows; human-required merges.
4. Reuse evidence contract v2 (claims validation, extend base/delta/human evidence, exhaustive new, privacy/runtime, future-date rejection).
5. Representative golden-path and source-defined completeness requirement.
6. Evaluator + physical mapper behavior as implemented in reuse.py / physical.py with negative tests.