ssot-cli 0.1.5__tar.gz → 0.1.6.dev1__tar.gz

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssot-cli
-Version: 0.1.5
+Version: 0.1.6.dev1
 Summary: Primary CLI distribution for ssot-registry.
 Author-email: Jacob Stewart <jacob@swarmauri.com>
 License-Expression: Apache-2.0
@@ -24,8 +24,8 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Utilities
 Requires-Python: <3.14,>=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: ssot-contracts<0.3.0,>=0.2.10
-Requires-Dist: ssot-core<0.3.0,>=0.2.10
+Requires-Dist: ssot-contracts<0.3.0,>=0.2.11.dev1
+Requires-Dist: ssot-core<0.3.0,>=0.2.11.dev1
 Requires-Dist: tomli>=2.0.1; python_version < "3.11"
 
 <div align="center">
@@ -84,6 +84,26 @@ Boundaries and releases are intentionally different:
 - Freezing a boundary locks that resolved scope and emits a boundary snapshot.
 - A release points at a frozen boundary and then bundles claims and evidence for certify, promote, publish, and revoke workflows.
 
+## Entity intent
+
+Operators should read the top-level entity commands this way:
+
+- `adr`: architectural decision records that capture why the system is designed the way it is.
+- `spec`: specification documents that define normative, operational, governance, or local-policy contract.
+- `feature`: implementation units that connect planning, delivery status, tests, claims, and SPEC coverage.
+- `profile`: reusable capability or deployment bundles composed from features and nested profiles.
+- `test`: verification rows that point at executable or procedural checks.
+- `claim`: tiered statements about system behavior that must be supported by tests and evidence.
+- `evidence`: concrete artifacts, reports, bundles, or logs that substantiate tests and claims.
+- `issue`: plannable defects or work items that may block a release.
+- `risk`: tracked exposure that must be mitigated, accepted, or retired.
+- `boundary`: scoped delivery definition used to decide what a release is evaluated against.
+- `release`: publication unit tied to a frozen boundary plus the claims and evidence needed for certification.
+- `graph`: relationship export view of the registry.
+- `registry`: full-document export view of the registry.
+
+Each command's `--help` now describes not just what it does mechanically, but why an operator would use it and what each flag is meant to control.
+
 ## CLI quick reference
 
 ```bash

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/README.md

@@ -54,6 +54,26 @@ Boundaries and releases are intentionally different:
 - Freezing a boundary locks that resolved scope and emits a boundary snapshot.
 - A release points at a frozen boundary and then bundles claims and evidence for certify, promote, publish, and revoke workflows.
 
+## Entity intent
+
+Operators should read the top-level entity commands this way:
+
+- `adr`: architectural decision records that capture why the system is designed the way it is.
+- `spec`: specification documents that define normative, operational, governance, or local-policy contract.
+- `feature`: implementation units that connect planning, delivery status, tests, claims, and SPEC coverage.
+- `profile`: reusable capability or deployment bundles composed from features and nested profiles.
+- `test`: verification rows that point at executable or procedural checks.
+- `claim`: tiered statements about system behavior that must be supported by tests and evidence.
+- `evidence`: concrete artifacts, reports, bundles, or logs that substantiate tests and claims.
+- `issue`: plannable defects or work items that may block a release.
+- `risk`: tracked exposure that must be mitigated, accepted, or retired.
+- `boundary`: scoped delivery definition used to decide what a release is evaluated against.
+- `release`: publication unit tied to a frozen boundary plus the claims and evidence needed for certification.
+- `graph`: relationship export view of the registry.
+- `registry`: full-document export view of the registry.
+
+Each command's `--help` now describes not just what it does mechanically, but why an operator would use it and what each flag is meant to control.
+
 ## CLI quick reference
 
 ```bash

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ssot-cli"
-version = "0.1.5"
+version = "0.1.6.dev1"
 description = "Primary CLI distribution for ssot-registry."
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 license = "Apache-2.0"
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 dependencies = [
-  "ssot-contracts>=0.2.10,<0.3.0",
-  "ssot-core>=0.2.10,<0.3.0",
+  "ssot-contracts>=0.2.11.dev1,<0.3.0",
+  "ssot-core>=0.2.11.dev1,<0.3.0",
   "tomli>=2.0.1; python_version < '3.11'",
 ]
 keywords = ["ssot", "cli", "registry", "governance", "release-management", "validation", "developer-tools"]

ssot_cli-0.1.6.dev1/src/ssot_cli/adr_cmd.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import argparse
+
+from ssot_registry.api import (
+    create_document,
+    create_document_reservation,
+    delete_document,
+    get_document,
+    list_document_reservations,
+    list_documents,
+    set_document_status,
+    sync_documents,
+    supersede_documents,
+    update_document,
+)
+from ssot_cli.common import add_path_argument, compact_dict
+
+
+def register_adr(subparsers: argparse._SubParsersAction) -> None:
+    adr = subparsers.add_parser(
+        "adr",
+        help="ADR operations.",
+        description="Architectural decision records capture why the system is designed the way it is and preserve decision history.",
+    )
+    adr_sub = adr.add_subparsers(dest="adr_command", required=True)
+
+    create = adr_sub.add_parser(
+        "create",
+        help="Author a new architectural decision record.",
+        description="Create an ADR that captures a design decision, its rationale, and its document source.",
+    )
+    add_path_argument(create)
+    create.add_argument("--title", required=True, help="Human-readable ADR title shown to operators and reviewers.")
+    create.add_argument("--slug", required=True, help="Stable slug used to derive the ADR document id and filename.")
+    create.add_argument("--body", default=None, help="Inline ADR body text to persist without a separate authored payload file.")
+    create.add_argument("--body-file", default=None, help="Path to the ADR YAML or JSON body payload to import into the registry.")
+    create.add_argument("--number", type=int, default=None, help="Explicit ADR number to assign instead of auto-allocation.")
+    create.add_argument("--status", choices=["draft", "in_review", "accepted", "rejected", "withdrawn", "superseded", "retired"], default="draft", help="Current decision lifecycle state for the ADR.")
+    create.add_argument("--note", default=None, help="Lifecycle note that explains review, acceptance, or retirement context.")
+    create.add_argument("--origin", choices=["repo-local", "ssot-origin", "ssot-core"], default="repo-local", help="Source authority for the ADR document.")
+    create.add_argument("--reserve-range", default=None, help="Named reservation range to allocate the ADR number from.")
+    create.set_defaults(func=run_create)
+
+    get = adr_sub.add_parser("get", help="Show one ADR.", description="Fetch a single ADR by id for review or automation.")
+    add_path_argument(get)
+    get.add_argument("--id", required=True, help="ADR id to retrieve.")
+    get.set_defaults(func=run_get)
+
+    list_cmd = adr_sub.add_parser("list", help="List ADRs.", description="List ADR documents currently known to the registry.")
+    add_path_argument(list_cmd)
+    list_cmd.set_defaults(func=run_list)
+
+    update = adr_sub.add_parser(
+        "update",
+        help="Edit a repo-local ADR.",
+        description="Update mutable ADR fields such as title, body source, status, or lifecycle note.",
+    )
+    add_path_argument(update)
+    update.add_argument("--id", required=True, help="ADR id to update.")
+    update.add_argument("--title", default=None, help="Replacement ADR title.")
+    update.add_argument("--body", default=None, help="Replacement inline ADR body text.")
+    update.add_argument("--body-file", default=None, help="Replacement ADR body file to ingest.")
+    update.add_argument("--status", choices=["draft", "in_review", "accepted", "rejected", "withdrawn", "superseded", "retired"], default=None, help="New lifecycle state for the ADR.")
+    update.add_argument("--note", default=None, help="Updated lifecycle note or rationale.")
+    update.set_defaults(func=run_update)
+
+    set_status = adr_sub.add_parser(
+        "set-status",
+        help="Advance or revise ADR status.",
+        description="Change the lifecycle state of an ADR without editing other document fields.",
+    )
+    add_path_argument(set_status)
+    set_status.add_argument("--id", required=True, help="ADR id whose status should change.")
+    set_status.add_argument("--status", required=True, choices=["draft", "in_review", "accepted", "rejected", "withdrawn", "superseded", "retired"], help="Target lifecycle state to set.")
+    set_status.add_argument("--note", default=None, help="Reason or context for the status transition.")
+    set_status.set_defaults(func=run_set_status)
+
+    supersede = adr_sub.add_parser(
+        "supersede",
+        help="Mark older ADRs as replaced.",
+        description="Record that one ADR supersedes one or more earlier ADRs.",
+    )
+    add_path_argument(supersede)
+    supersede.add_argument("--id", required=True, help="Newer ADR that supersedes prior decisions.")
+    supersede.add_argument("--supersedes", nargs="+", required=True, help="ADR ids that are being replaced by `--id`.")
+    supersede.add_argument("--note", default=None, help="Transition note explaining why the older ADRs were superseded.")
+    supersede.set_defaults(func=run_supersede)
+
+    delete = adr_sub.add_parser("delete", help="Delete a repo-local ADR.", description="Remove a repo-local ADR entry and its associated document metadata.")
+    add_path_argument(delete)
+    delete.add_argument("--id", required=True, help="ADR id to delete.")
+    delete.set_defaults(func=run_delete)
+
+    sync = adr_sub.add_parser("sync", help="Refresh packaged ADRs.", description="Sync packaged ADR documents from installed sources into the repository.")
+    add_path_argument(sync)
+    sync.set_defaults(func=run_sync)
+
+    reserve = adr_sub.add_parser("reserve", help="Manage ADR number ranges.", description="Reserve ADR number ranges for a team, owner, or local namespace.")
+    reserve_sub = reserve.add_subparsers(dest="adr_reserve_command", required=True)
+    reserve_create = reserve_sub.add_parser("create", help="Reserve ADR numbers.", description="Create a repo-local reservation range for ADR numbering.")
+    add_path_argument(reserve_create)
+    reserve_create.add_argument("--name", required=True, help="Reservation owner or label.")
+    reserve_create.add_argument("--start", type=int, required=True, help="First ADR number included in the reservation.")
+    reserve_create.add_argument("--end", type=int, required=True, help="Last ADR number included in the reservation.")
+    reserve_create.set_defaults(func=run_reserve_create)
+
+    reserve_list = reserve_sub.add_parser("list", help="List ADR reservations.", description="Show ADR numbering reservations currently defined in the repository.")
+    add_path_argument(reserve_list)
+    reserve_list.set_defaults(func=run_reserve_list)
+
+
+def run_create(args: argparse.Namespace) -> dict[str, object]:
+    return create_document(
+        args.path,
+        "adr",
+        title=args.title,
+        slug=args.slug,
+        body=args.body,
+        body_file=args.body_file,
+        number=args.number,
+        origin=args.origin,
+        reserve_range=args.reserve_range,
+        status=args.status,
+        note=args.note,
+    )
+
+
+def run_get(args: argparse.Namespace) -> dict[str, object]:
+    return get_document(args.path, "adr", args.id)
+
+
+def run_list(args: argparse.Namespace) -> dict[str, object]:
+    return list_documents(args.path, "adr")
+
+
+def run_update(args: argparse.Namespace) -> dict[str, object]:
+    changes = compact_dict({"title": args.title, "body": args.body, "body_file": args.body_file, "status": args.status, "note": args.note})
+    if not changes:
+        raise ValueError("At least one update field is required")
+    return update_document(args.path, "adr", args.id, **changes)
+
+
+def run_set_status(args: argparse.Namespace) -> dict[str, object]:
+    return set_document_status(args.path, "adr", args.id, status=args.status, note=args.note)
+
+
+def run_supersede(args: argparse.Namespace) -> dict[str, object]:
+    return supersede_documents(args.path, "adr", args.id, supersedes=args.supersedes, note=args.note)
+
+
+def run_delete(args: argparse.Namespace) -> dict[str, object]:
+    return delete_document(args.path, "adr", args.id)
+
+
+def run_sync(args: argparse.Namespace) -> dict[str, object]:
+    return sync_documents(args.path, "adr")
+
+
+def run_reserve_create(args: argparse.Namespace) -> dict[str, object]:
+    return create_document_reservation(args.path, "adr", name=args.name, start=args.start, end=args.end)
+
+
+def run_reserve_list(args: argparse.Namespace) -> dict[str, object]:
+    return list_document_reservations(args.path, "adr")
+

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/src/ssot_cli/boundary_cmd.py

@@ -25,65 +25,65 @@ def register_boundary(subparsers: argparse._SubParsersAction) -> None:
     )
     boundary_sub = boundary.add_subparsers(dest="boundary_command", required=True)
 
-    create = boundary_sub.add_parser("create", help="Create a boundary.")
+    create = boundary_sub.add_parser("create", help="Define a release boundary.", description="Create a scoped delivery boundary that selects the features and profiles a release is evaluated against.")
     add_path_argument(create)
-    create.add_argument("--id", required=True)
-    create.add_argument("--title", required=True)
-    create.add_argument("--status", choices=["draft", "active", "frozen", "retired"], default="draft")
-    add_optional_bool_argument(create, "--frozen", default=False, help_text="Whether the boundary is frozen.")
-    create.add_argument("--feature-ids", nargs="*", default=[])
-    create.add_argument("--profile-ids", nargs="*", default=[])
+    create.add_argument("--id", required=True, help="Normalized boundary id to create.")
+    create.add_argument("--title", required=True, help="Human-readable boundary title.")
+    create.add_argument("--status", choices=["draft", "active", "frozen", "retired"], default="draft", help="Current lifecycle state of the boundary.")
+    add_optional_bool_argument(create, "--frozen", default=False, help_text="Record whether the boundary contents are locked against further scope edits.")
+    create.add_argument("--feature-ids", nargs="*", default=[], help="Direct feature ids included in the scoped delivery unit.")
+    create.add_argument("--profile-ids", nargs="*", default=[], help="Profile ids included in the scoped delivery unit.")
     create.set_defaults(func=run_create)
 
-    get = boundary_sub.add_parser("get", help="Get one boundary.")
+    get = boundary_sub.add_parser("get", help="Show one boundary.", description="Fetch a single boundary by id.")
     add_path_argument(get)
-    get.add_argument("--id", required=True)
+    get.add_argument("--id", required=True, help="Boundary id to retrieve.")
     get.set_defaults(func=run_get)
 
-    list_cmd = boundary_sub.add_parser("list", help="List boundaries.")
+    list_cmd = boundary_sub.add_parser("list", help="List boundaries.", description="List boundary records currently known to the registry.")
     add_path_argument(list_cmd)
     list_cmd.set_defaults(func=run_list)
 
-    update = boundary_sub.add_parser("update", help="Update boundary fields.")
+    update = boundary_sub.add_parser("update", help="Edit boundary metadata.", description="Update mutable boundary fields without changing the feature or profile membership lists.")
     add_path_argument(update)
-    update.add_argument("--id", required=True)
-    update.add_argument("--title", default=None)
-    update.add_argument("--status", choices=["draft", "active", "frozen", "retired"], default=None)
-    add_optional_bool_argument(update, "--frozen", default=None, help_text="Set frozen state.")
+    update.add_argument("--id", required=True, help="Boundary id to update.")
+    update.add_argument("--title", default=None, help="Replacement boundary title.")
+    update.add_argument("--status", choices=["draft", "active", "frozen", "retired"], default=None, help="Updated lifecycle state.")
+    add_optional_bool_argument(update, "--frozen", default=None, help_text="Change whether the boundary is locked against scope edits.")
     update.set_defaults(func=run_update)
 
-    delete = boundary_sub.add_parser("delete", help="Delete a boundary.")
+    delete = boundary_sub.add_parser("delete", help="Delete a boundary.", description="Remove a boundary record from the registry.")
     add_path_argument(delete)
-    delete.add_argument("--id", required=True)
+    delete.add_argument("--id", required=True, help="Boundary id to delete.")
     delete.set_defaults(func=run_delete)
 
-    add_feature = boundary_sub.add_parser("add-feature", help="Add feature ids to a boundary.")
+    add_feature = boundary_sub.add_parser("add-feature", help="Add features to a boundary.", description="Include one or more direct features in the scoped delivery boundary.")
     add_path_argument(add_feature)
-    add_feature.add_argument("--id", required=True)
-    add_feature.add_argument("--feature-ids", nargs="+", required=True)
+    add_feature.add_argument("--id", required=True, help="Boundary id that should receive the features.")
+    add_feature.add_argument("--feature-ids", nargs="+", required=True, help="Feature ids to include in the boundary.")
     add_feature.set_defaults(func=run_add_feature)
 
-    remove_feature = boundary_sub.add_parser("remove-feature", help="Remove feature ids from a boundary.")
+    remove_feature = boundary_sub.add_parser("remove-feature", help="Remove features from a boundary.", description="Remove one or more direct features from the scoped delivery boundary.")
     add_path_argument(remove_feature)
-    remove_feature.add_argument("--id", required=True)
-    remove_feature.add_argument("--feature-ids", nargs="+", required=True)
+    remove_feature.add_argument("--id", required=True, help="Boundary id whose features should be removed.")
+    remove_feature.add_argument("--feature-ids", nargs="+", required=True, help="Feature ids to remove from the boundary.")
     remove_feature.set_defaults(func=run_remove_feature)
 
-    add_profile = boundary_sub.add_parser("add-profile", help="Add profile ids to a boundary.")
+    add_profile = boundary_sub.add_parser("add-profile", help="Add profiles to a boundary.", description="Include one or more profiles in the scoped delivery boundary.")
     add_path_argument(add_profile)
-    add_profile.add_argument("--id", required=True)
-    add_profile.add_argument("--profile-ids", nargs="+", required=True)
+    add_profile.add_argument("--id", required=True, help="Boundary id that should receive the profiles.")
+    add_profile.add_argument("--profile-ids", nargs="+", required=True, help="Profile ids to include in the boundary.")
     add_profile.set_defaults(func=run_add_profile)
 
-    remove_profile = boundary_sub.add_parser("remove-profile", help="Remove profile ids from a boundary.")
+    remove_profile = boundary_sub.add_parser("remove-profile", help="Remove profiles from a boundary.", description="Remove one or more profiles from the scoped delivery boundary.")
     add_path_argument(remove_profile)
-    remove_profile.add_argument("--id", required=True)
-    remove_profile.add_argument("--profile-ids", nargs="+", required=True)
+    remove_profile.add_argument("--id", required=True, help="Boundary id whose profiles should be removed.")
+    remove_profile.add_argument("--profile-ids", nargs="+", required=True, help="Profile ids to remove from the boundary.")
     remove_profile.set_defaults(func=run_remove_profile)
 
-    freeze = boundary_sub.add_parser("freeze", help="Freeze a boundary and emit a snapshot.")
+    freeze = boundary_sub.add_parser("freeze", help="Freeze boundary scope.", description="Lock a boundary's resolved scope and emit a snapshot suitable for release workflows.")
     add_path_argument(freeze)
-    freeze.add_argument("--boundary-id", default=None, help="Boundary id. Defaults to the active boundary.")
+    freeze.add_argument("--boundary-id", default=None, help="Boundary id to freeze. Omit to freeze the active boundary.")
     freeze.set_defaults(func=run_freeze)
 
 

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/src/ssot_cli/claim_cmd.py

@@ -32,72 +32,72 @@ def register_claim(subparsers: argparse._SubParsersAction) -> None:
     )
     claim_sub = claim.add_subparsers(dest="claim_command", required=True)
 
-    create = claim_sub.add_parser("create", help="Create a claim.")
+    create = claim_sub.add_parser("create", help="Register a new assurance claim.", description="Create a tiered claim about system behavior and link it to supporting features, tests, and evidence.")
     add_path_argument(create)
-    create.add_argument("--id", required=True)
-    create.add_argument("--title", required=True)
-    create.add_argument("--status", choices=["proposed", "declared", "implemented", "asserted", "evidenced", "certified", "promoted", "published", "blocked", "retired"], default="proposed")
-    create.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default="T0")
-    create.add_argument("--kind", required=True)
-    create.add_argument("--description", default="")
-    create.add_argument("--feature-ids", nargs="*", default=[])
-    create.add_argument("--test-ids", nargs="*", default=[])
-    create.add_argument("--evidence-ids", nargs="*", default=[])
+    create.add_argument("--id", required=True, help="Normalized claim id to create.")
+    create.add_argument("--title", required=True, help="Human-readable claim title.")
+    create.add_argument("--status", choices=["proposed", "declared", "implemented", "asserted", "evidenced", "certified", "promoted", "published", "blocked", "retired"], default="proposed", help="Current maturity or publication state of the claim.")
+    create.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default="T0", help="Assurance tier required for the claim.")
+    create.add_argument("--kind", required=True, help="Operator-defined claim category.")
+    create.add_argument("--description", default="", help="What the claim asserts and why it matters.")
+    create.add_argument("--feature-ids", nargs="*", default=[], help="Feature ids the claim is about.")
+    create.add_argument("--test-ids", nargs="*", default=[], help="Test ids that support the claim.")
+    create.add_argument("--evidence-ids", nargs="*", default=[], help="Evidence ids that substantiate the claim.")
     create.set_defaults(func=run_create)
 
-    get = claim_sub.add_parser("get", help="Get one claim.")
+    get = claim_sub.add_parser("get", help="Show one claim.", description="Fetch a single claim record by id.")
     add_path_argument(get)
-    get.add_argument("--id", required=True)
+    get.add_argument("--id", required=True, help="Claim id to retrieve.")
     get.set_defaults(func=run_get)
 
-    list_cmd = claim_sub.add_parser("list", help="List claims.")
+    list_cmd = claim_sub.add_parser("list", help="List claims.", description="List claim records currently known to the registry.")
     add_path_argument(list_cmd)
     list_cmd.set_defaults(func=run_list)
 
-    update = claim_sub.add_parser("update", help="Update claim fields.")
+    update = claim_sub.add_parser("update", help="Edit claim metadata.", description="Update mutable claim fields without changing its linked support graph.")
     add_path_argument(update)
-    update.add_argument("--id", required=True)
-    update.add_argument("--title", default=None)
-    update.add_argument("--kind", default=None)
-    update.add_argument("--description", default=None)
+    update.add_argument("--id", required=True, help="Claim id to update.")
+    update.add_argument("--title", default=None, help="Replacement claim title.")
+    update.add_argument("--kind", default=None, help="Updated claim category.")
+    update.add_argument("--description", default=None, help="Replacement claim description.")
     update.set_defaults(func=run_update)
 
-    delete = claim_sub.add_parser("delete", help="Delete a claim.")
+    delete = claim_sub.add_parser("delete", help="Delete a claim.", description="Remove a claim record from the registry.")
     add_path_argument(delete)
-    delete.add_argument("--id", required=True)
+    delete.add_argument("--id", required=True, help="Claim id to delete.")
     delete.set_defaults(func=run_delete)
 
-    link = claim_sub.add_parser("link", help="Link a claim to features, tests, or evidence.")
+    link = claim_sub.add_parser("link", help="Attach related records to a claim.", description="Add links from a claim to the features, tests, or evidence that support it.")
     add_path_argument(link)
-    link.add_argument("--id", required=True)
-    link.add_argument("--feature-ids", nargs="*")
-    link.add_argument("--test-ids", nargs="*")
-    link.add_argument("--evidence-ids", nargs="*")
+    link.add_argument("--id", required=True, help="Claim id that should receive the links.")
+    link.add_argument("--feature-ids", nargs="*", help="Feature ids to attach.")
+    link.add_argument("--test-ids", nargs="*", help="Test ids to attach.")
+    link.add_argument("--evidence-ids", nargs="*", help="Evidence ids to attach.")
     link.set_defaults(func=run_link)
 
-    unlink = claim_sub.add_parser("unlink", help="Unlink a claim from features, tests, or evidence.")
+    unlink = claim_sub.add_parser("unlink", help="Remove related records from a claim.", description="Remove links from a claim to features, tests, or evidence.")
     add_path_argument(unlink)
-    unlink.add_argument("--id", required=True)
-    unlink.add_argument("--feature-ids", nargs="*")
-    unlink.add_argument("--test-ids", nargs="*")
-    unlink.add_argument("--evidence-ids", nargs="*")
+    unlink.add_argument("--id", required=True, help="Claim id whose links should be removed.")
+    unlink.add_argument("--feature-ids", nargs="*", help="Feature ids to detach.")
+    unlink.add_argument("--test-ids", nargs="*", help="Test ids to detach.")
+    unlink.add_argument("--evidence-ids", nargs="*", help="Evidence ids to detach.")
     unlink.set_defaults(func=run_unlink)
 
-    evaluate = claim_sub.add_parser("evaluate", help="Evaluate one claim or all claims.")
+    evaluate = claim_sub.add_parser("evaluate", help="Evaluate claim support.", description="Recompute claim support and readiness for one claim or the entire registry.")
     add_path_argument(evaluate)
-    evaluate.add_argument("--claim-id", default=None, help="Claim id to evaluate. Omit to evaluate all claims.")
+    evaluate.add_argument("--claim-id", default=None, help="Claim id to evaluate. Omit to evaluate every claim in the registry.")
     evaluate.set_defaults(func=run_evaluate)
 
-    set_status = claim_sub.add_parser("set-status", help="Set claim status.")
+    set_status = claim_sub.add_parser("set-status", help="Advance or revise claim status.", description="Change the lifecycle status of a claim without editing other fields.")
     add_path_argument(set_status)
-    set_status.add_argument("--id", required=True)
-    set_status.add_argument("--status", required=True, choices=["proposed", "declared", "implemented", "asserted", "evidenced", "certified", "promoted", "published", "blocked", "retired"])
+    set_status.add_argument("--id", required=True, help="Claim id whose status should change.")
+    set_status.add_argument("--status", required=True, choices=["proposed", "declared", "implemented", "asserted", "evidenced", "certified", "promoted", "published", "blocked", "retired"], help="Target lifecycle or publication state.")
     set_status.set_defaults(func=run_set_status)
 
-    set_tier = claim_sub.add_parser("set-tier", help="Set claim tier.")
+    set_tier = claim_sub.add_parser("set-tier", help="Change claim tier.", description="Set the assurance tier expected for a claim.")
     add_path_argument(set_tier)
-    set_tier.add_argument("--id", required=True)
-    set_tier.add_argument("--tier", required=True, choices=["T0", "T1", "T2", "T3", "T4"])
+    set_tier.add_argument("--id", required=True, help="Claim id whose tier should change.")
+    set_tier.add_argument("--tier", required=True, choices=["T0", "T1", "T2", "T3", "T4"], help="Target assurance tier to assign.")
     set_tier.set_defaults(func=run_set_tier)
 
 

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/src/ssot_cli/common.py

@@ -5,7 +5,12 @@ from typing import Any
 
 
 def add_path_argument(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("path", nargs="?", default=".", help="Registry file path or repository root.")
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Repository root or registry file to operate on. Defaults to the current directory.",
+    )
 
 
 def add_id_argument(parser: argparse.ArgumentParser, flag: str = "--id", *, dest: str | None = None, help_text: str = "Normalized id.") -> None:
@@ -34,4 +39,3 @@ def collect_list_fields(args: argparse.Namespace, mapping: dict[str, str]) -> di
         if value:
             links[field_name] = value
     return links
-

{ssot_cli-0.1.5 → ssot_cli-0.1.6.dev1}/src/ssot_cli/evidence_cmd.py

@@ -29,59 +29,59 @@ def register_evidence(subparsers: argparse._SubParsersAction) -> None:
     )
     evidence_sub = evidence.add_subparsers(dest="evidence_command", required=True)
 
-    create = evidence_sub.add_parser("create", help="Create an evidence row.")
+    create = evidence_sub.add_parser("create", help="Register a new evidence artifact.", description="Create an evidence row that points at a concrete artifact supporting tests or claims.")
     add_path_argument(create)
-    create.add_argument("--id", required=True)
-    create.add_argument("--title", required=True)
-    create.add_argument("--status", choices=["planned", "collected", "passed", "failed", "stale"], default="planned")
-    create.add_argument("--kind", required=True)
-    create.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default="T0")
-    create.add_argument("--evidence-path", dest="evidence_path", required=True, help="Repository-relative evidence path.")
-    create.add_argument("--claim-ids", nargs="*", default=[])
-    create.add_argument("--test-ids", nargs="*", default=[])
+    create.add_argument("--id", required=True, help="Normalized evidence id to create.")
+    create.add_argument("--title", required=True, help="Human-readable evidence title.")
+    create.add_argument("--status", choices=["planned", "collected", "passed", "failed", "stale"], default="planned", help="Current freshness or outcome state of the evidence artifact.")
+    create.add_argument("--kind", required=True, help="Operator-defined evidence category such as report, bundle, or log.")
+    create.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default="T0", help="Assurance tier the evidence contributes toward.")
+    create.add_argument("--evidence-path", dest="evidence_path", required=True, help="Repository-relative location of the evidence artifact.")
+    create.add_argument("--claim-ids", nargs="*", default=[], help="Claim ids supported by the evidence.")
+    create.add_argument("--test-ids", nargs="*", default=[], help="Test ids associated with the evidence.")
     create.set_defaults(func=run_create)
 
-    get = evidence_sub.add_parser("get", help="Get one evidence row.")
+    get = evidence_sub.add_parser("get", help="Show one evidence row.", description="Fetch a single evidence record by id.")
     add_path_argument(get)
-    get.add_argument("--id", required=True)
+    get.add_argument("--id", required=True, help="Evidence id to retrieve.")
     get.set_defaults(func=run_get)
 
-    list_cmd = evidence_sub.add_parser("list", help="List evidence rows.")
+    list_cmd = evidence_sub.add_parser("list", help="List evidence rows.", description="List evidence artifacts currently known to the registry.")
     add_path_argument(list_cmd)
     list_cmd.set_defaults(func=run_list)
 
-    update = evidence_sub.add_parser("update", help="Update evidence fields.")
+    update = evidence_sub.add_parser("update", help="Edit evidence metadata.", description="Update mutable evidence fields without changing its link graph.")
     add_path_argument(update)
-    update.add_argument("--id", required=True)
-    update.add_argument("--title", default=None)
-    update.add_argument("--status", choices=["planned", "collected", "passed", "failed", "stale"], default=None)
-    update.add_argument("--kind", default=None)
-    update.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default=None)
-    update.add_argument("--evidence-path", dest="evidence_path", default=None)
+    update.add_argument("--id", required=True, help="Evidence id to update.")
+    update.add_argument("--title", default=None, help="Replacement evidence title.")
+    update.add_argument("--status", choices=["planned", "collected", "passed", "failed", "stale"], default=None, help="Updated freshness or outcome state.")
+    update.add_argument("--kind", default=None, help="Updated evidence category.")
+    update.add_argument("--tier", choices=["T0", "T1", "T2", "T3", "T4"], default=None, help="Updated assurance tier contribution.")
+    update.add_argument("--evidence-path", dest="evidence_path", default=None, help="Updated repository-relative path to the artifact.")
     update.set_defaults(func=run_update)
 
-    delete = evidence_sub.add_parser("delete", help="Delete an evidence row.")
+    delete = evidence_sub.add_parser("delete", help="Delete an evidence row.", description="Remove an evidence record from the registry.")
     add_path_argument(delete)
-    delete.add_argument("--id", required=True)
+    delete.add_argument("--id", required=True, help="Evidence id to delete.")
     delete.set_defaults(func=run_delete)
 
-    link = evidence_sub.add_parser("link", help="Link evidence to claims or tests.")
+    link = evidence_sub.add_parser("link", help="Attach related claims or tests.", description="Add links from an evidence row to the claims or tests it supports.")
     add_path_argument(link)
-    link.add_argument("--id", required=True)
-    link.add_argument("--claim-ids", nargs="*")
-    link.add_argument("--test-ids", nargs="*")
+    link.add_argument("--id", required=True, help="Evidence id that should receive the links.")
+    link.add_argument("--claim-ids", nargs="*", help="Claim ids to attach.")
+    link.add_argument("--test-ids", nargs="*", help="Test ids to attach.")
     link.set_defaults(func=run_link)
 
-    unlink = evidence_sub.add_parser("unlink", help="Unlink evidence from claims or tests.")
+    unlink = evidence_sub.add_parser("unlink", help="Remove related claims or tests.", description="Remove links from an evidence row to claims or tests.")
     add_path_argument(unlink)
-    unlink.add_argument("--id", required=True)
-    unlink.add_argument("--claim-ids", nargs="*")
-    unlink.add_argument("--test-ids", nargs="*")
+    unlink.add_argument("--id", required=True, help="Evidence id whose links should be removed.")
+    unlink.add_argument("--claim-ids", nargs="*", help="Claim ids to detach.")
+    unlink.add_argument("--test-ids", nargs="*", help="Test ids to detach.")
     unlink.set_defaults(func=run_unlink)
 
-    verify = evidence_sub.add_parser("verify", help="Verify one evidence row or all evidence rows.")
+    verify = evidence_sub.add_parser("verify", help="Verify evidence artifacts.", description="Check one evidence row or all evidence rows for existence and readiness.")
     add_path_argument(verify)
-    verify.add_argument("--evidence-id", default=None, help="Evidence id to verify. Omit to verify all rows.")
+    verify.add_argument("--evidence-id", default=None, help="Evidence id to verify. Omit to verify every evidence row in the registry.")
     verify.set_defaults(func=run_verify)