Concepts

Long-form companion to Overview. Day-to-day artifacts live under .authright/.

IAM Brief

The host LLM writes .authright/brief/brief.yaml (aperture, capabilities, slices, grounding) before --analyze. That file is living judgment, not a Decision Lock. authright init does not create it. --analyze, --set, --confirm-plan, and --ready fail closed if it is missing or invalid. scan / doctor / review / to-openspec / to-plan on already DECIDED work do not require it.

Aperture is bounded or unbounded (not a vendor-product enum). Optional coverage is delta (default; related-optional Skip stays default) or analogue (inventory then bind: now capabilities must have catalog ids or stay adjacent Decision Gaps; analogue inventory is must, not Skip). Greenfield empty CurrentState and brownfield snapshot deltas are both valid ground. An Auth Change locks one accepted slice (accepted_for_lock then locked after --ready). Unbounded remainder stays later / non_goal on the Brief. Recommended on a choose is not selected. The CLI does not invent omitted analogue rows or tech.* ids from brand names.

There is no /auth:brief or /auth:program or /auth:solution. Dual Decide after slice accept is two UIs: /auth:explore (Agenda HITL) vs /auth:change (auto-plan). Must coverage follows the accepted Brief slice for both commands — they differ in presentation (one-at-a-time recommend-and-choose vs full plan table with optional recommended auto-map), not in which must items exist for that slice. A thin delta Brief (including a vague “add IAM” ask without a named product) keeps unbound lifecycle work off both paths. A full analogue inventory opens bound lifecycle and assurance must work on both. SP-only analogue does not invent IdP lifecycle must slots. Explore is not a fixed short conventional IAM quiz independent of the Brief.

Domain objects

Knowledge Graph / ASKG is an internal substrate that delivered skills may query; it is not a primary user-facing Graph UI. Decision Graph rankings are advisory artifacts, not automatic locks.

Four semantic layers

The Technology Registry catalog is not overlay-merged into Project KG facts. Scan persists this-project instance nodes (project.local, module.* from Repository Context, state.<facet> CurrentState for observed/inferred Must-domain facets) plus claims that may reference registry ids. Those instance nodes are not Decision Locks and are not an RBAC role catalog. .authright/context.yaml evidence, unconfirmed notes, and unknowns are a projection of project-layer KG records after scan (plus collected signals, snapshot, and repository context). Unconfirmed notes are not decisions. Decision Lock remains decisions.yaml + --ready.

AuthRight Decision (a lock) is not an IAM AuthorizationDecision. Token Claim is not an ASKG claim. AuthRight Design (after --ready, including sparse migration.yaml) is not a lock and is not a /auth:design command. After Design is projected, the CLI Design Validator checks ontology and decision consistency; DESIGN_CONFLICT blocks --ready lock and handoff (to-openspec / to-plan). Mixed Project KG claims alone are not DESIGN_CONFLICT. The validator is not a Decision Lock. Browse the shipped concept model on the site Ontology page (interactive graph; read-only).

Decision Graph node states follow DISCOVERED → ANALYZING → CANDIDATES_GENERATED → WAITING_HITL → SELECTED → VALIDATED → LOCKED (plus INVALID / BLOCKED / SUPERSEDED). --analyze ranks; --ready locks.

Repository Context and hybrid repos

authright scan records Repository Context beside IAM signals. When a repo has sibling build roots (e.g. Vite frontend/ + Maven/Python/Go backend/), scan partitions surfaces and enriches each with a Technology Pack. Nested Maven modules stay under the parent surface.

Downstream (change --analyze, Keep-current-style templates after an answered strategy, handoff export) uses surfaces so locked IdP/protocol decisions land with pack-idiomatic constraints per surface — not a single wrong-stack recipe. Product/framework names in pack_defaults come only from observed or locked integration mechanisms (registry templates); unresolved mechanisms yield generic language. Auto-plan does not lock showcase IdPs or weak SP patterns solely from recommended. Packs describe where/how; the Technology Registry / Decision Graph still owns which IdP/protocol. Rank-1 / recommended is a label on a Human Interaction choose, not an accepted decision. After upgrading AuthRight, re-analyze open changes so stale impact/pack_defaults regenerate.

IAM Domain Snapshot and first-party IdP admin

authright scan classifies an IAM Domain Snapshot (trust role, authentication methods, federation, session/token, authorization, identity administration, provisioning, risk, audit) as observe/infer only — not a Decision Lock. Scan also records five discovery classes (structural, technology, iam, convention, security) and ScanFindings. A finding is not a Gap; Gaps live under .authright/knowledge/project/gaps.yaml only when a Requirement (change intent on decision-graph.yaml at --analyze) is compared to CurrentState. Constitution rule text is not a Requirement. Host agents present HITL and author judgment artifacts; the CLI stays deterministic for classify, rank, draft, and lock gates.

When identity_role is first-party IdP or hybrid, Decide uses three independent admin axes after login methods:

• Object breadth (identity_admin_scope): core / groups / org / org_and_resource, or explicit defer:identity_admin_scope
• Admin UX completeness (identity_admin_ux): crud / detail / operational / audit (required unless scope is deferred). Levels are cumulative. At crud or higher, OpenSpec recipes are WHEN-qualified: when Repository Context has a UI-shaped surface, Admin UI must expose create / update / disable (and in-scope binding editors) for each in-scope admin object from the locked scope profile (object-generic — not limited to User/Role/Group); API write endpoints alone do not satisfy. When no UI-shaped surface is in scope, Admin API mutation suffices. List-only or detail-read-only Admin screens are non-conformant under CRUD-or-higher when UI-shaped. Silent keep UI/UX / keep_style constrain visual language and entry placement; they do not waive Admin UI mutation.
• User attribute profile (user_profile_scope): identity / standard / enterprise / custom, or defer:user_profile_scope (required when User is in a non-deferred object set). This is not object breadth — org is not required solely to store department-like User fields.

Declared ontology concepts can carry a decision variable (one, set, or level). The CLI projects the question: alignment says what was committed, the registry supplies lockable ids, and project knowledge marks a current member without accepting it. The host model writes alignment, an optional recommendation subset, and the sentence in questions.yaml. The CLI does not call a model and does not accept a decision from that prose. A wide request opens one variable. Extra legal options are further selections on that same variable. A practice with no compiled id stays unresolved; it is not a new question and filler spans are not Decision Gaps. Recommended pairings (for example groups+detail+standard when admin is unknown) are labels across orthogonal admin variables (object breadth, UX completeness, user profile), not one bundled lock. An underspecified “support login” commitment is one authentication-method set with a minimum of one; only registered methods are offered. Greenfield and brownfield both enter the identity_role axis through /auth:change (option questions, then --analyze). Uncovered remainder after those closed axes becomes a Decision Gap (decision_gap HITL) — graph unknowns are not automatically gaps. Projected OpenSpec includes SCIM-aligned User/Group attributes from selected profile buckets and Admin information architecture (including WHEN-qualified CRUD mutation floors)—not CRUD-only one-liners that leave Admin UI list-only when a UI-shaped surface exists. SCIM protocol endpoints are a later change. AuthRight is not an IdP/IAM runtime.

User Lifecycle & Assurance

Everyday capabilities—sign-up, forgot-password / account recovery, MFA, provisioning, post-login self-service (profile, authenticated change-password, social link/unlink, MFA factor manage, session revoke), trusted-device management, close/delete own account, identity proofing, step-up, adaptive risk, organization / B2B tenancy, end-user consent, and identity brokering—are covered as closed Decide slots when catalog-bound, not as AuthRight product runtimes and not as new slash intents.

• Slots open when the owning ontology concept is effectively committed (host alignment, Brief ontology_concept_id bind, or CLI semantic/related-enables.yaml after Enable). An IAM-shaped change or a Domain Snapshot facet alone does not open every lifecycle question.
• Password trichotomy: forgot/recovery ≠ authenticated change-password ≠ admin password-reset.
• MFA dichotomy: org policy (mfa_capability) ≠ end-user factor manage (mfa_self_service). Step-up and adaptive risk are distinct from MFA policy.
• Authentication methods include passkey, magic link, TOTP, social, push, and email OTP (in addition to password and mobile OTP) when the registry seeds them.
• Integration: bind authority IdPs and social/consumer IdPs as registry entities. Identity brokering (identity_brokering + external_idp_set) ≠ AccountLinking ≠ SP social-rp. Personal Microsoft Account ≠ Entra ID. Vendor overlays hint Capability names plus optional concept/IdP lists — not Decide locks; AuthRight does not evaluate Conditional Access / Ping Protect.
• Dependents: login_identifier only after registration_channel=self_registration; recovery_proof only after account_recovery=self_service; external_idp_set only after identity_brokering=enable.
• registration_channel=jit_federation (account creation channel) is orthogonal to provisioning_mechanism=jit.
• Related-optional offers (third Decide lane): after IdP/hybrid sign-in must decisions, vocabulary may list optional enhancements (signup, recovery, MFA, self-service, trusted-device, closure, brokering, …) with preview options for the primary slot. Default skip on delta; they do not block --confirm-plan / --ready. Enable with authright change <id> --enable-offer <offer_id> then --set <slot>=<option_id> from the listed options (does not rewrite host alignment). Ontology concepts are not labeled intrinsically must or related.

Language and stack support

More languages and stacks will follow. If scan does not detect a pack, AuthRight still records IAM signals; pack-idiomatic landing stays Core-only until that stack ships.

Change id

Format: AUTH-YYYY-NNNN. The id is immutable. The folder may include a slug; renaming the slug does not change the id.

Artifact layout (after init)

.authright/
├── config.yaml
├── context.yaml
├── constitution.yaml
├── knowledge/              # ASKG YAML (commit with .authright/)
│   └── project/
├── logs/                   # local JSONL black box (gitignored)
├── diagnosis/
│   └── report.md           # doctor: risk report you should open (from /auth:doctor)
├── findings/
│   └── <timestamp>/        # doctor CLI helpers only — not the main report
├── changes/
│   └── AUTH-YYYY-NNNN-<slug>/
│       ├── intent.md
│       ├── context.md
│       ├── analysis.md
│       ├── request-match.md      # does the locked plan still match what you asked?
│       ├── decisions.yaml
│       ├── decision-package.yaml
│       ├── security.md
│       ├── contract.md
│       ├── openspec.yaml
│       └── status.yaml
└── reviews/
    └── AUTH-YYYY-NNNN/
        ├── semantic.md          # host LLM; write before `authright review`
        ├── report.md
        └── result.yaml

Lifecycle

Happy path:

DRAFT → ANALYZED → DECISION_REQUIRED → DECIDED → EXPORTED →
IMPLEMENTING → IMPLEMENTED → REVIEWING → VERIFIED

Also: DECISION_CONFLICT, SECURITY_FAILURE, VERIFICATION_FAILED.

Only legal lifecycle moves succeed. Prefer authright change <id> --ready to lock DECIDED on the happy path. DECISION_REQUIRED is manual only.

Decision Lock

Accepted Auth Decisions must not be silently inverted while coding agents implement via OpenSpec. Use authright review to check conformance.

Rule priority (reasoning)

1. Critical security invariant
2. Project Constitution
3. Accepted decisions
4. Industry best practice
5. Agent preference

OpenSpec bridge

authright to-openspec and authright to-plan are two handoff commands—pick one. to-openspec (propose-first) emits authright-feed.md + authright-claims.yaml from the same Binding expansions as to-plan / shared gather (not locks-only; readable surface labels), then OpenSpec propose authors the package with observable Scenarios preferred over claim-dump scaffolding; AuthRight coverage is a floor (extras OK; quality warnings non-blocking). to-plan writes .authright/changes/<dir>/agent-plan/ for Plan mode (OpenSpec not required). Refine tasks.md without inventing new AuthRight locks. Re-export can refresh an EXPORTED change; use --force-tasks to regenerate tasks. See Implementation · OpenSpec · Agent Plan-mode.

Doctor vs doc

Two easy-to-mix commands:

• /auth:doctor — looks at your app source and writes what’s risky today → .authright/diagnosis/report.md
• /auth:doc — writes a summary of decisions already on disk → .authright/docs/

Neither edits your application code. Doctor does not lock a new design; follow up with explore or change when you’re ready to fix something.

Related

• Glossary
• Workflows
• CLI