Updated concepts - added projects

Signed-off-by: Steve Springett <steve@springett.us>

Author: stevespringett

docs/astro.config.mjs

@@ -65,6 +65,7 @@ export default defineConfig({
           items: [
             { label: 'Dashboards', slug: 'user-guide/dashboards' },
             { label: 'Entities', slug: 'user-guide/entities' },
+            { label: 'Projects', slug: 'user-guide/projects' },
             { label: 'Standards', slug: 'user-guide/standards' },
             { label: 'Assessments', slug: 'user-guide/assessments' },
             {

docs/src/content/docs/getting-started/first-assessment.md

@@ -34,7 +34,7 @@ Navigate to Activity → Assessments and click New Assessment. In the form:
 3. Choose yourself as the assessor. Leave the assessee fields blank for the walkthrough; you are playing both roles.
 4. Set a short scope ("Walkthrough assessment for the getting-started guide") and a target completion date a week from today.
 
-Save the assessment. The system creates a claim placeholder for every requirement in the standard and puts the assessment in Planned state. Move it into In Progress to start work.
+Save the assessment. It opens in the New state. Click Start to move it to In Progress. The system loads the requirements from the standard and creates a claim placeholder for each one.
 
 ## Step 4: Work a single claim
 
@@ -58,7 +58,7 @@ For the walkthrough you can leave the remaining claims unrated, or batch-mark th
 
 From the assessment detail page, click Complete. The system checks that every claim has a final state (Met, Not Met, Partially Met, Not Applicable, or Inconclusive). If any are still Pending, the action is blocked with a list of the offenders. For the walkthrough, set any remaining claims to Not Applicable, then try again.
 
-The assessment moves into Review state. Click Approve to finalize it.
+The assessment moves to the Complete state. Its claims and evidence are now read only, and a conformance score is calculated.
 
 ## Step 8: Produce the attestation
 

docs/src/content/docs/introduction/concepts.md

@@ -23,12 +23,34 @@ An entity is the subject of an assessment. It is whatever the organization decid
 
 Entities can be related to each other. A product entity might depend on a service entity that depends on a vendor entity. The [Entities](/user-guide/entities/) page explains how the relationship graph is navigated in the UI.
 
+## Project
+
+A project is an organizational container that groups related assessments together. Projects are useful when you need to assess the same entity (or set of entities) against multiple standards, coordinate a compliance initiative that spans several teams, or track a time bounded engagement such as an annual review or a vendor onboarding cycle.
+
+Each project is associated with one or more standards. When you create an assessment inside a project, the system pulls the requirements from the project's standards automatically. Projects have their own lifecycle states (New, In Progress, On Hold, Complete, Operational, Retired), their own start and due dates, and a dashboard that aggregates conformance scores, evidence coverage, timeline health, and warnings across every assessment in the project.
+
+Projects are optional. A standalone assessment that evaluates one entity against one standard does not need a project. Projects become valuable when the work is large enough that you want a single place to see progress, manage deadlines, and export a consolidated report.
+
 ## Assessment
 
-An assessment is a scoped engagement that evaluates one entity against one standard over a defined period. It has a start date, an end date, a team of participants (assessors and assessees), and a state machine that tracks whether it is being planned, executed, reviewed, or completed.
+An assessment is a scoped engagement that evaluates one entity against one standard over a defined period. It has a start date, an end date, a team of participants (assessors and assessees), and a lifecycle state machine that governs what actions are available at each stage.
 
 An assessment produces one or more claims, and ultimately, when the participants sign off, it produces an attestation. Multiple assessments can exist for the same entity against the same standard at different points in time; the platform treats them as distinct historical records.
 
+### Assessment lifecycle
+
+Every assessment moves through a defined set of states.
+
+| State | Description |
+|-------|-------------|
+| New | Initial state. The scope, team, and schedule are configured but no claim work has started. Moving to In Progress loads requirements and sets the start date. |
+| Pending | Optional holding state for assessments waiting on prerequisites before work can begin. |
+| In Progress | Active working state. Assessors draft claims, request evidence, and record rationale. Assessees respond with evidence and clarification. |
+| On Hold | Pause state for assessments that are temporarily blocked. Returns to In Progress when the blocker is resolved. |
+| Cancelled | Terminal state for assessments that will not be finished. Remains in the system for historical reference. |
+| Complete | All claims have a final rating and the system has calculated a conformance score. Read only. Can be reopened (back to In Progress) or archived. |
+| Archived | Final resting state. Irreversible. Cannot be reopened or modified in any way. |
+
 ## Claim
 
 A claim is the assessor's structured assertion about a single requirement inside an assessment. A claim has a state (met, partially met, not met, not applicable, inconclusive), a rationale written by the assessor, and a list of supporting evidence.
@@ -57,4 +79,4 @@ A role is a bundle of permissions that governs what a user can do in the platfor
 
 ## Where these concepts live in the platform
 
-Standards, requirements, entities, assessments, claims, evidence, and attestations each have a dedicated area in the navigation. The [Tour](/getting-started/tour/) page shows you where each one lives. The [User Guide](/user-guide/dashboards/) covers each in depth with screenshots and common workflows.
+Standards, requirements, entities, projects, assessments, claims, evidence, and attestations each have a dedicated area in the navigation. The [Tour](/getting-started/tour/) page shows you where each one lives. The [User Guide](/user-guide/dashboards/) covers each in depth with screenshots and common workflows.

docs/src/content/docs/reference/glossary.md

@@ -7,7 +7,11 @@ This glossary is alphabetical. Terms that belong together are cross referenced s
 
 ## Assessment
 
-The workspace where a standard is applied to an entity over a defined scope and period. An assessment ties together an entity, a standard, an assessor team, an assessee team, a schedule, and the claims that result from evaluating each requirement in the standard. Assessments move through states (draft, in progress, under review, complete, published) and produce an [attestation](#attestation) when complete.
+The workspace where a standard is applied to an entity over a defined scope and period. An assessment ties together an entity, a standard, an assessor team, an assessee team, a schedule, and the claims that result from evaluating each requirement in the standard. Assessments move through a defined [lifecycle](#assessment-lifecycle) (New, Pending, In Progress, On Hold, Cancelled, Complete, Archived) and produce an [attestation](#attestation) when complete.
+
+## Assessment lifecycle
+
+The state machine that governs an [assessment](#assessment). Valid states are New (created but not started), Pending (awaiting prerequisites), In Progress (active claim work), On Hold (temporarily paused), Cancelled (abandoned), Complete (all claims finalized, read only), and Archived (permanently sealed). Key transitions: start moves New to In Progress, complete moves In Progress to Complete, reopen moves Complete back to In Progress, and archive moves Complete to Archived. Archived is irreversible. See [Assessments](/user-guide/assessments/) for the full workflow.
 
 ## Assessor
 
@@ -77,6 +81,14 @@ The Open Worldwide Application Security Project. The nonprofit that sponsors Cyc
 
 A named capability in the application. Every action is gated by a permission key (for example `assessments.create`, `claims.rate`, `admin.encryption.rotate`). Permissions are granted through [roles](#role); they cannot be granted directly to users.
 
+## Project
+
+An organizational container that groups related [assessments](#assessment) under a shared set of [standards](#standard), a timeline, and an aggregate dashboard. Projects are useful for coordinated compliance initiatives, annual reviews, vendor onboarding cycles, or any engagement that spans multiple assessments. Projects have their own lifecycle states (New, In Progress, On Hold, Complete, Operational, Retired) and can be exported as a consolidated CycloneDX attestation or a summary report. See [Projects](/user-guide/projects/) for the full guide.
+
+## Project state
+
+The lifecycle position of a [project](#project). Valid states are New (just created), In Progress (active work), On Hold (paused), Complete (objectives met), Operational (long running continuous program), and Retired (archived, read only).
+
 ## Requirement
 
 A single normative statement in a [standard](#standard). Requirements form a hierarchy: a top level requirement can have children that decompose it into smaller obligations. Each requirement has a stable ID, a textual statement, optional metadata, and references to authoritative documents.

docs/src/content/docs/user-guide/assessments.md

@@ -7,21 +7,29 @@ An assessment is a scoped engagement that evaluates one entity against one stand
 
 ## The assessment lifecycle
 
-Every assessment moves through four states: Planned, In Progress, Review, and Completed. The state machine is deliberate: a claim state cannot regress from Completed back to In Progress without an explicit reopen action, because the integrity of the audit trail depends on forward-only transitions.
+Every assessment moves through a defined set of states. The state machine is deliberate: transitions are forward only by default, and reversing a completed assessment requires an explicit reopen action, because the integrity of the audit trail depends on controlled state changes.
 
-Planned is the initial state. The assessment has a scope, a team, and a reference to a specific version of a standard, but the assessor has not yet started working through claims. The assessor opens the assessment and moves it to In Progress when work begins.
+| State | Description |
+|-------|-------------|
+| New | Initial state. The scope, team, entity, standard, and schedule are configured but no claim work has started. Requirements have not yet been loaded. |
+| Pending | Optional holding state for assessments waiting on prerequisites before work can begin, such as a pending approval or a dependency on another assessment. |
+| In Progress | Active working state. When started, the system loads requirements from the associated standard (or from the project's or entity's standards, depending on scope) and creates a claim placeholder for each one. The start date is set automatically. Assessors draft claims, request evidence, and record rationale. Assessees respond with evidence and clarification. |
+| On Hold | Pause state for assessments that are temporarily blocked. Returns to In Progress when the blocker is resolved. Claims and evidence remain accessible in read only mode. |
+| Cancelled | Terminal state for assessments that will not be finished. Remains in the system for historical reference but cannot be modified. |
+| Complete | All requirements have a claim with a final rating (Met, Partially Met, Not Met, Not Applicable, or Inconclusive). The system calculates a conformance score and sets the end date. Read only. Two actions are available: reopen (returns to In Progress, clears end date) and archive (seals permanently). |
+| Archived | Final resting state. Irreversible. Cannot be reopened or modified in any way. Exists solely as a historical record. |
 
-In Progress is the active state. The assessor navigates the requirements tree and works each requirement, drafting claims, requesting evidence, and recording the reasoning. The assessee responds to requests, attaches evidence, and clarifies questions. Both parties collaborate inside the same assessment; there is no back-and-forth over email because everything happens inside the record.
+### Valid transitions
 
-Review is the state between work-is-done and sign-off. The assessor moves the assessment to Review once every claim has a final state (Met, Partially Met, Not Met, Not Applicable, or Inconclusive). The reviewer (often a senior assessor, sometimes the entity owner) reads the claims in aggregate and checks that the narrative is consistent, the evidence is sufficient, and the conclusions are defensible. The reviewer can send the assessment back to In Progress with comments if something is not ready.
+The following transitions are enforced by the system:
 
-Completed is the terminal state. A completed assessment is an immutable historical record. Its claims and evidence can no longer be edited, which is precisely what a downstream consumer of the attestation wants. If the entity is later reassessed against the same standard, a new assessment is created; the old one is preserved.
+New to In Progress (start), New to Pending, Pending to In Progress, In Progress to On Hold, On Hold to In Progress, In Progress to Complete, In Progress to Cancelled, Complete to In Progress (reopen), and Complete to Archived (archive). No other transitions are permitted.
 
 ## Planning an assessment
 
 From Activity → Assessments, click New Assessment. The form captures the subject (entity), the reference (standard and version), the scope, the schedule (start and target completion dates), and the team. The team is a list of users with roles inside the assessment: Assessor, Reviewer, and Assessee. A single user can play multiple roles if the installation's permission model allows it.
 
-When you save the form the system creates a claim placeholder for every requirement in the standard. The assessment opens in Planned state; move it to In Progress to begin.
+When you save the form the assessment opens in the New state. Start the assessment to move it to In Progress, at which point the system loads the requirements from the standard and creates a claim placeholder for each one.
 
 ## Working claims
 
@@ -43,9 +51,9 @@ Assessments support threaded comments on every claim. A comment can be addressed
 
 ## Finalizing the assessment
 
-To move an assessment to Review, every claim must have a final state. The Complete action checks the condition and lists any claims that still need attention if it cannot succeed. Once in Review, the designated Reviewer walks through the assessment and signs off.
+To complete an assessment, every requirement must have a claim with a final rating. The Complete action checks this condition and lists any claims that still need attention if it cannot succeed. Once complete, the assessment is read only and a conformance score is calculated.
 
-Signing off moves the assessment to Completed. The Produce Attestation action on a completed assessment generates the CDXA document. See [Producing Attestations](/user-guide/producing-attestations/) for the signing and export workflow.
+The Produce Attestation action on a completed assessment generates the CDXA document. See [Producing Attestations](/user-guide/producing-attestations/) for the signing and export workflow. If something needs to change after completion, the Reopen action returns the assessment to In Progress. Once finalized for good, the Archive action seals the assessment permanently.
 
 ## Reassessing