Terminology

The words we use, and exactly what they mean.

SDLC.works is a system, so its vocabulary is precise on purpose. Every term below is defined the way the platform itself declares it. If a word in the console or the docs is unclear, it is defined here.

Organization & identity

Who is acting, and on whose behalf.

  • Principal

    A recognized actor, human or software; the platform treats both the same. Your credential identifies exactly one principal, and nothing you send can name another.

  • Organization

    The shared space that owns names, members and projects. A shared organization can be dissolved only once it holds no projects.

  • Personal namespace

    The private space every person always has. It cannot be dissolved, so if you lose access to a shared organization your session moves there instead of logging you out.

  • Member

    A person who belongs to an organization. A membership carries roles.

  • Role

    Permission to use a named filter. Your authority is always a subset of the platform’s own list of actions; there is no separate permission system.

  • Filter

    A named rule saying which platform actions, and which uses of them, are allowed. It knows nothing about people; attaching it to a member makes it a role. An organization’s last working authority cannot be revised away, and a filter still in use cannot be retired.

  • Held identity

    A revocable login a member creates so a machine (a CI job, a script) can act as that member, never with more authority. Revoking it ends it permanently but keeps its history.

  • Invitation

    A pending offer to join an organization, accepted or declined with your verified email, or withdrawn by the inviter.

  • Cognition credential

    Your personal AI coding-assistant login, captured with a short code from the provider. It follows you into every organization but is never shared with one. Withdrawing it stops new workspaces; running ones keep their access until they end.

  • Resident agent

    The platform’s own AI member, sdlc-ai, added to your organization when you connect an AI provider. You must already be allowed to add members for this to happen.

  • Billing standing

    Whether your organization is in good standing to take actions that cost money. Card details never pass through the platform.

Projects, branches & source code

Where your software lives and how it moves forward.

  • Project

    One undertaking inside an organization, such as one app or one client site. It holds its system branches and all its conversations. In the console a project is simply called an SDLC.

  • System branch

    One version of your whole software world: its layout of services and infrastructure, settings, integrations, source code, processes, history and running resources, kept separate from every other branch. A system can have more than one meaningful shape at once without the shapes contaminating each other.

  • Branch transformer

    A named rule, stored in the project, that derives a new branch from a parent branch. New branches are only ever made this way, so every new version follows a stated rule instead of a hand copy.

  • Generation

    Each branch derived from its parent is a new generation. The platform evolves by adding branches and actions, never by putting version numbers in its web addresses.

  • Code repository

    A repository on a code host such as GitHub, attached as the source for one or more components.

  • Recipe

    The sdlc.toml file in your repository that says what it builds for which components. If it disagrees with the branch, the platform records the disagreement by name instead of guessing.

  • Codebase region

    Source code the platform stores itself, inside your own storage, instead of in a git repository. It is started once from a seed or from nothing, then moves forward only by snapshots.

  • Source-hosting store

    The storage integration where a branch’s codebase region physically lives. A branch with no such store has no codebase region.

  • Codebase snapshot

    A saved state of the codebase region, numbered in sequence and identified by its content. Each snapshot names the one before it, so two people cannot save conflicting versions at once.

  • Codebase seed

    A published starter codebase, identified by its content, that a region can be started from. Trust in a seed only goes up: unwitnessed, then asserted, then constructed once the platform has proved it builds.

  • Content object

    Raw file bytes uploaded to the platform and identified by their fingerprint, before any record refers to them. Uploading the same bytes again gives the same answer; stored objects never change.

  • Source state

    An exact, content-identified version of a component’s source. Builds and runs are pinned to it.

Topology & infrastructure

The declared shape of a branch.

  • Tech-stack config

    The whole declared shape of a branch’s software: components, infrastructure, URL registers, artifact registries and the connections between them. It is checked as a whole on every change, so everything downstream can trust it is consistent.

  • Component

    A unit of your application software: a service, website or worker. It has a serving port, routes open to the public, environment settings, check commands and a place it is deployed.

  • Infra

    A declared piece of infrastructure built from a catalogued type, such as a cluster, database or bucket. Components run on these.

  • Connection

    How one entity uses another, for example a service using a database. The data passed must match the format the providing side publishes.

  • Realization target

    Where a component is deployed: the infrastructure plus deployment settings, which build label to use and how versions are chosen. A stateful component has at most one active target.

  • URL register

    A declared claim on a public web address. The address actually assigned is recorded and can be read back.

  • Artifact registry

    A declared place where build outputs are published, such as a container registry or GitHub Releases.

  • Capability catalogue

    The list of infrastructure, URL-register and artifact-registry types a branch can use, taken from bundles that have been built successfully. An empty catalogue only means nothing has been built on this branch yet.

  • Bundle

    A build output that also carries catalogue information. Building one fills or refreshes the branch’s catalogue.

  • World-facing route

    A URL path prefix where a component accepts anonymous public visitors. Each prefix is declared once and must not clash with another.

  • Visual entry

    The one serving component marked as the branch’s main customer-facing screen. At most one per branch.

  • KV

    A branch’s named settings and secrets, checked against a declared schema that also records which values are confidential. Adding one key never rewrites another key’s definition.

  • Deferred-binding reference

    A placeholder written as $[[ … ]] meaning “the value comes from there later”, such as a KV key or an output of provisioned infrastructure. The topology stays free of hard-coded values, so it works in any environment.

  • Integration

    A named connection to an outside service family: cloud, code repository, artifact store, runner client, Pulumi, AI provider, SDLC connection or task provider. Each is added, updated or removed on its own and holds its own credentials, so you rotate a key in one place.

  • Task provider

    An execution-environment service where tasks and workspaces run. A branch can declare several under names you choose, with a strict preference order.

  • Environment actor

    An outside party at the platform’s edge, such as the operator, code host, sandbox provider or payment processor.

Delivery & runtime

From a commit to something live.

  • Workflow

    A named process declared on a branch, such as build, release or provision. System workflows cannot be edited.

  • Schedule

    Runs set up to start at a chosen point from a chosen source commit.

  • Run

    One recorded execution, pinned to exact source states. Runs are how outside executors do the work the platform never does itself.

  • Runner client

    The integration that sends workflow runs to an outside CI runner, such as GitHub Actions or AWS CodeBuild, and watches them. The platform never creates or edits workflow files in your repository.

  • Runner

    A machine you control that the platform cannot reach. It collects waiting runs itself under a time-limited lease and reports progress and the result.

  • Task

    One unit of hosted execution, such as an agent session or environment setup. The platform records it before any provider acts, then logs each step.

  • Workspace

    A resumable development session on your own task provider, tied to one branch and one conversation, working on a copy of the branch’s repository. Ending it either keeps the source safely or discards it explicitly.

  • Artifact

    A recorded reference to a build output, a file or container image, held in a store with its digest and origin. Registering the same output again does not create a duplicate.

  • Carrier bundle

    The platform’s own published toolchain package, copied onto your branch as the carrier component’s default artifact.

  • Release

    Approving one component version built from an exact set of artifacts, under the component’s versioning rules. If it is not allowed, you get a readable reason, not an error.

  • Deployment ledger

    The per-component history of approved releases, plus a pointer to the one that is live. Rollback moves the pointer back; nothing is rebuilt.

  • Provisioned estate

    The branch’s real running resources: their IDs, outputs, assigned addresses and whether they match the declaration. The platform keeps bringing them in line with the declared topology.

  • Deployment mode

    A branch setting for how going live happens: on_tag_push (the default), on_commit_push or manual. An automatic branch chains build, release and deploy; a manual branch waits for an operator.

  • Preview

    A live link to a branch’s running app, created by its infrastructure. The address can change over time.

  • Promotion

    Moving work from a branch toward production. It refuses anything that does not converge.

  • Plane

    A separate copy of the whole platform, such as qa or production, each with its own records and logins.

  • Observability

    One combined view of a branch’s recent tasks, agent sessions, check commands and visual entry.

Agents, conversations & planning

How people and agents work together.

  • Conversation

    A permanent, add-only list of messages that belongs to exactly one project. It may branch off a parent thread and may note which system branch it concerns. Only participants can post; anyone in the project can read.

  • Agent

    Whoever a conversation message is credited to: a person, or a machine participant such as a platform assistant, tool or held identity. An agent is not the same as a principal or a member.

  • Agent turn

    One request to an agent with the full message history. A streamed turn saves nothing; a dispatched turn saves the reply into the conversation.

  • AI provider

    The integration through which the platform’s agents reach a language model.

  • Planning connection

    An optional, per-project link to a planning tool such as Linear or Jira. Any combination, or none, is allowed; writes are off by default, and planning is never required for delivery.

  • Capability ceiling

    The most a planning connection is deliberately allowed to do.

  • Planning operation

    A planning action recorded once with a fixed identity. If it is unclear whether the provider received it, the outcome stays unknown and is never retried blindly; a person can record the match by hand.

  • SDLC connection

    An integration that connects one SDLC platform instance to another.

  • Issue report

    A platform problem filed to the operator’s issue tracker; the reply carries the tracker’s issue ID.

How the platform behaves

The rules every action follows.

  • Intent

    A named platform action, such as branch.declare or kv.read. The list of intents is the compatibility contract; web addresses are only where intents are reached.

  • Declaration

    Stating the shape you want. It is checked as a whole, never piecemeal.

  • Attestation

    Recording evidence that something was built, provisioned or released.

  • Reading

    Every action that is neither a declaration nor an attestation.

  • Convergent

    Repeating an action gives the same result instead of a duplicate, so retries, crashes and replays never split the world in two.

  • Witness

    An identity derived from evidence, such as content or a digest, that later decisions are stamped against.

  • Named refusal

    Every refusal or mismatch comes back as readable meaning with a name, such as project_not_found, never as a raw error.

  • Obligation-bearing intent

    An action that can create a charge, so it can be refused when billing standing is bad.

  • Platform guide

    What the platform tells a new client about itself: its domain, its reference language, its topology rules and its vocabularies.

Inside the repository

Words our own engineers use to keep the platform honest.

  • Designer

    The one role that may change subsystem structure and the testing rules. The designer also decides which tools sit behind the console.

  • Subsystem declaration

    A SUBSYSTEM.md file declaring a node’s name, definition, inputs and outputs. Together these files are the authoritative structure; code is corrected to match them.

  • Declared interior

    Folders exempt from needing a subsystem declaration because they hold no behaviour of their own.

  • Claim

    A statement tests must prove, generated from the declared structure and never written by hand. A node claim says a node produces what it declares; a relation claim says what one side sends is what the other requires.

  • Ownership

    Each claim has exactly one owning verifier: a test, a static check or a proving-ground scenario. No owner is a coverage gap; two owners is redundancy.

  • Claim debt

    The list of known unowned claims. It can only shrink; listed gaps are reported but do not block CI.

  • Fidelity verdict

    The drift checker’s findings with a pass or fail decision. It gates pushes to qa and is report-only on main.

  • Deployable

    One of the shippable apps. Each needs a smoke test: the smallest meaningful end-to-end operation through it.

  • Proving ground

    Headless end-to-end scenarios that prove whole-platform behaviours.

  • Impact closure

    The tests chosen for a change by following the declared structure, not code imports: the affected nodes, their connections and what depends on them.

  • Schema migration law

    Database migrations may only add things. Removals ship in a separate later commit, after the release that stopped using them is live.

  • Conduct

    The platform’s internal record of one hosted agent session: what it may do and how many sub-tasks it may run at once. Never shown to customers.

  • Root witness

    The platform’s private record that a hosted top-level agent session started and how it progressed, used to verify history and route corrections back to the same session.

  • Devloop recovery

    Internal tracking of a top-level agent’s development loop after failed release attempts, so a replacement host can carry on without losing or redoing work.