---
title: "Concept Registry — types and lifecycle of decision criteria"
description: "Propose Concepts with evidence and adopt decision criteria through human review. Follow YAML examples, semantic fields, revisions, sources, links, and recovery."
---

# Concept Registry — types and lifecycle of decision criteria

Of the two registries in [Company](/en/docs/company), Concepts hold reusable team decision criteria. This guide explains how to propose a criterion with evidence, have a human review and publish it, and use it after adoption. Session agents read projected YAML under `aachat/teams/<team>/concepts/`, edit it, and propose changes with `chat registry`.

## kind — Vision, Issue, and Policy

A Concept has one of three kinds. Choose it by the question the Concept answers. kind describes the content's role only; the semantic axes below (guidance_strength, etc.) are never derived automatically from kind.

| kind | Question it answers | Use |
|---|---|---|
| `vision` | What state do we want to realize? | A future or state the company wants to realize |
| `issue` | What currently prevents the Vision? | An important problem or gap the company must keep recognizing. Keep one-Project tasks and bugs in that Project |
| `policy` | What do we prioritize when making this kind of decision? | A reusable decision or action policy for moving toward a Vision and addressing Issues |

## Semantic axes — 6 axes

A Concept has 6 semantic axes independent of kind. YAML for a new Concept requires `scope` (domain + tags), `abstraction_level`, `time_horizon`, `guidance_strength`, and `maturity`. There is no automatic mapping such as `policy = governing`, and none is inferred from review counts either.

| Axis | Values | Meaning |
|---|---|---|
| **guidance_strength** (how strongly it directs judgment) | `contextual` / `guiding` / `governing` | `governing` is used as a standard premise; deviating from it requires a reason. `guiding` should be followed in principle but can be overridden with a reason given stronger evidence or a conflicting governing Concept. `contextual` is used as input only when relevant |
| **maturity** (how settled the revision is) | `exploratory` / `provisional` / `established` | `established` can be taken as a premise without re-examination. `provisional` should have its sources or latest reviews checked for high-impact decisions. `exploratory` may be included in published context but must not be restated as settled fact |
| **abstraction_level** (scope of impact) | `foundational` / `directional` / `structural` / `tactical` / `operational` | Chosen by the scope of judgment it affects, never inferred from kind |
| **time_horizon** (time frame) | `today` / `one_week` / `one_month` / `three_months` / `one_year` / `three_years` / `ten_years` / `enduring` | Every value except `enduring` requires an `expires_at`. After expiry, the Concept is excluded from current published context |
| **domain** (area of applicability) | `company` / `organization` / `product` / `marketing` / `sales` | Choose the one broad area the Concept applies to. Team-internal classifications such as product, customer segment, or initiative go in `scope.tags` (up to 20) |
| **applicability** (validity) | `active` / `expired` | A derived state based on `expires_at` |

`governing + established` is a standard premise. `governing + provisional` must always be considered, checking sources or the latest review for high-impact decisions. `governing + exploratory` must always surface but must not be blindly followed. When governing Concepts conflict with each other, or an unresolved concern exists, don't pick a winner by score — read links, sources, and reviews and surface the unresolved conflict explicitly.

## Revision model

A Concept is an immutable stack of revisions. The current revision is never rewritten directly; every change is recorded as a new proposed revision.

- A revision's `status` is one of `pending` / `published` / `declined`
- **A Concept can have at most one pending revision at a time.** A new proposal cannot be submitted while one is already pending
- **Only humans (a team's Owner/Admin) can publish or decline.** Agents can only propose
- **A decline requires a reason.** The next session should read that reason and calibrate its criteria before deciding whether to re-propose
- Once created, a revision's content is immutable. Even changes to wording, sources, scope, or time horizon are recorded as a new revision

Title is capped at 80 characters and description at 300 — they are an entry point, not a summary; the detailed evidence is read through sources (below).

## Reviews

Both pending and published revisions can carry two kinds of review: `endorse` and `concern`. A `concern` requires a comment (an `endorse`'s comment is optional), and can be resolved with a resolution note. A published revision may still be read as a premise even with an open `concern`, but for decisions that depend heavily on that Concept, check the current revision's comments with `aachat_concept_reviews` and surface that the concern exists. Post a review with `aachat_concept_review`; projected `concepts/_index.yaml` carries only `open_concern_count`.

## Links between Concepts

Concepts connect to each other through 8 directional relation types.

| relation | Meaning |
|---|---|
| `realizes` | Realizes |
| `constrains` | Constrains |
| `addresses` | Addresses |
| `measures` | Measures |
| `supports` | Supports |
| `contradicts` | Contradicts |
| `refines` | Refines |
| `depends_on` | Depends on |

Links also have a lifecycle: `candidate` / `accepted` / `retired` / `rejected`. An agent can propose a link as a `candidate` by editing a Concept YAML link and running `chat registry submit`, but **it counts as a valid relationship for the Concept Map or for judgment only once accepted. Only humans (a team's Owner/Admin) can accept, reject, or retire a link.**

When a published Concept would mislead future decisions, an agent can send an archive proposal to the Review queue with `aachat_concept_removal_propose`. For an accepted Link, remove it from the Concept YAML and run `chat registry submit --reason` to propose retirement. The Map does not change until a human accepts it, and history remains as an archived Concept or retired Link.

## Similarity gate on proposal

`chat registry submit` for a new Concept automatically checks it against existing Concepts before registration. If a similar Concept is found, the proposal is not registered and `similar_found` is returned instead.

- **A similar `published` Concept** — a decision criterion already exists. Withdraw, or switch to a link proposal or a review if there's a relationship. If the evidence reveals a durable gap, consider an `issue` + a `contradicts` link
- **A similar `declined` Concept** — a human already rejected this. Read the decline reason (`status_reason`) and don't repeat the same proposal
- **A similar `pending` Concept** — someone else's revision proposal is awaiting review. Don't submit a duplicate
- A match against a `pending` or `declined` Concept the caller lacks permission to see returns no content or ID — only `hidden_match_count`
- Only when the proposal is genuinely something different, resubmit with the returned `proceed_token` to register it anyway

## Sources

A proposal is submitted with sources attached. There are 4 kinds.

| kind | What it points to |
|---|---|
| `shared_document` | A Shared Document |
| `session` | A session |
| `external` | An external URL |
| `human_decision` | A human decision (a note) |

For a Session agent proposal, at least one source must belong to the Project selected by `--project`; other Project sources must also be in the same Team and Session coverage. A source's availability is shown as one of `accessible` / `restricted` / `unavailable`; don't guess at the content of a `restricted` source. `unavailable` means the source cannot currently be resolved; check for deletion or changes such as Session coverage.

## Archive / restore

A Concept can be archived and restored. This is a WebUI/human-only operation and is not exposed as an agent-facing MCP tool. Don't create new links to an archived Concept or one with no published content.

## Free placement on the Concept Map

The WebUI's Concepts screen has a map view. A card's position (`free_position`) can be moved by a human, or by an agent editing Concept YAML and running `chat registry submit`. Placement is shared soft context: proximity between Concepts can be a hint worth considering, but when it conflicts with sources, typed links, or semantic fields, those take precedence. Don't assert a relationship that appears only in placement as fact — if it looks important, treat it as a candidate for a link proposal instead.

## Propose a Concept with evidence

Open Concepts in the Team sidebar and inspect existing Concepts and the Review queue. If the policy or a pending revision already exists, read it and its reviews before proposing a duplicate. Check the [Company permissions table](/en/docs/company) first. The following steps are for a Session agent with Project write permission and coverage.

This example assumes that the `acme/help-center` Project has `docs/research/support-friction.md`, recording evidence that users could not find answers and explaining the proposed improvement. Replace the Team/Project, document kind, and document ID with real ones, read that evidence, and adapt the proposal. Do not submit a fictional source unchanged.

Run `chat registry refresh --all` and read `concepts/_index.yaml`. Then save this complete new file as `aachat/teams/acme/concepts/customer-self-service.concept.yaml`.

```yaml
format: aachat.team-concept/v1
id: null
kind: policy
title: Make answers easy to find
description: Prefer clear, searchable help before adding support channels.
scope:
  domain: product
  tags:
    - support
abstraction_level: directional
time_horizon: enduring
expires_at: null
guidance_strength: guiding
maturity: provisional
position: null
sources:
  - kind: shared_document
    project: "acme/help-center"
    document_kind: research
    doc_id: support-friction
restricted_source_count: 0
links: []
```

`id: null` means a new registration. New Concepts require `position: null` and `links: []`; change position and links separately after publication. A time horizon other than `enduring` needs a future expiry as a quoted RFC3339 timestamp. Supply 1–20 sources; a new Concept has `restricted_source_count: 0`.

From the workspace root, run these commands in order.

```sh
chat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
chat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry refresh --all
```

`check` validates local YAML; it does not guarantee that a source exists or that the server will authorize the operation. Confirm that `plan` contains the intended single operation. After `submit` accepts the proposal, a Team Owner/Admin reads its evidence and changes in the Concepts Review queue, then publishes it or declines with a reason. Acceptance of a submission is not adoption of its content.

Projected YAML represents published current content only. Do not resubmit because the file returns to its old content or a new pending proposal's text does not appear in the index. Check the receipt and Review queue. After human publication, refresh and confirm the current content matches the adopted revision.

### Separate revisions from position changes

For an existing Concept, refresh the file referenced by the index's `file` field. To improve its description, edit `description`, preserve its existing ID and other required fields, and repeat check → plan → submit. Changes to meaning, sources, or scope create a new pending revision. If a revision is already pending, check its review outcome first.

To change position only, replace `position: null` or the current position in the existing file with this block, leaving every other field unchanged. Do not save this fragment as the entire file.

```yaml
position:
  x: 240.0
  y: 120.0
```

Repeat check → plan → submit → refresh. A position-only change applies directly; it does not approve the Concept's meaning. Coordinates must be finite, with each axis between -1000000 and 1000000. Editing meaning and position together produces `mixed_edit`, so submit them separately.

### Propose as a human from a connected repo

Check that the Team projection is healthy in `aachat status`, then use these commands with the same YAML.

```sh
aachat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry refresh --all
```

This CLI has no `--project` or `--proceed-token`. The repo connection determines the Team; the server checks access to the Projects named in sources. Even an Owner/Admin's semantic submission is a proposal; publication is a separate decision. Clearing position to null is unsupported in the outside CLI. Removing an accepted Link also differs from an agent's retirement proposal: it is a human retirement operation requiring Owner/Admin and `--reason`.

## Follow sources and reviews

Open Sources from a Concept Map card's menu to follow its evidence. Open the card's detail to inspect current content, reviews, and History. Distinguish pending content in the Review queue from the currently published content. For example, if the policy above is published but has an open concern that some languages remain hard to search, do not restate it as proof that all users can help themselves.

`restricted` means you lack access to that source. Ask an authorized human to check the necessary evidence; do not infer its contents. For `unavailable`, the source cannot currently be resolved. Check for deletion or changed Session coverage and consider a revision with accessible evidence. The WebUI requires access to all sources before proposing a revision. In a Session agent YAML revision, preserve `restricted_source_count` and edit only visible sources. The server inherits restricted sources and checks the combined limit of 20. The index's `open_concern_count` does not explain concerns, so read the comments. Expiry excludes content from current decision context; it does not delete its adoption history.

Both the Concept source model and Registry YAML `sources` accept four kinds: `shared_document`, `session`, `external`, and `human_decision`. It does not accept `project_message`. Inspect omitted sources in the WebUI instead of reconstructing them in the projection. For Session agent proposals, `external` or `human_decision` sources alone do not satisfy the Project-source requirement.

## YAML constraints and recovery

Use UTF-8 and LF newlines, without unknown or duplicate keys, tabs, anchors, aliases, merge keys, or explicit tags. Preserve quoted UUIDs, timestamps, and file references. Use a meaningful lowercase ASCII slug and `id: null` for a new record; never rename an existing ID or assigned path. Do not edit generated `_index.yaml`. Each submit handles one file and one operation. Saving is not a server mutation, and deleting a file does not archive a Concept.

| Situation | Next action |
|---|---|
| `mixed_edit` | Separate meaning, position, and individual links; plan one operation at a time |
| `similar_found` | Read similar content and decline reasons. Only a Session agent that concludes this is a distinct proposal should add `--proceed-token` to the same submit |
| Stale state / OCC conflict | Preserve the local draft, fetch server current, and reapply the intended change. There is no automatic merge |
| `outcome_unknown` | Keep file bytes unchanged and rerun the exact submit command returned by the CLI. Do not start another submission until reconciliation finishes |
| Projection unavailable / revoked / stopped | Do not treat remaining files as current. Follow the reported blocker to restore the runtime or Team access |

For a similarity-gate retry, use the actual token returned by the command.

```sh
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center --proceed-token '<returned-proceed-token>'
```

Only for a conflict, preserve any needed local draft elsewhere before explicitly discarding changes to the affected file.

```sh
chat registry refresh aachat/teams/acme/concepts/customer-self-service.concept.yaml --discard-local
```

This discards local edits. Read current content, reapply only the intended differences, then repeat check → plan → submit. In a connected repo, replace `chat` with `aachat`. An ordinary refresh does not silently overwrite dirty files. For an unknown-result retry, the CLI uses retained inflight information to reconcile server state first; do not edit or delete that file or internal state.

## Related pages

- The two-layer overview and how to ask: [company](/en/docs/company)
- Entity's types and lifecycle: [company](/en/docs/company)
- Terms: [glossary](/en/docs/glossary)