specify-cli 1.1.1__tar.gz → 1.1.2__tar.gz

{specify_cli-1.1.1 → specify_cli-1.1.2}/.github/ISSUE_TEMPLATE/bundle_submission.yml

@@ -1,7 +1,7 @@
 name: Bundle Submission
 description: Submit your bundle metadata for community catalog validation
 title: "[Bundle]: Add "
-labels: ["enhancement", "needs-triage"]
+labels: ["triage-must-have"]
 body:
   - type: markdown
     attributes:
@@ -16,7 +16,7 @@ body:
         - If you host a bundle catalog, test catalog installation with `specify bundle catalog add <catalog-url> --id <catalog-id> --policy install-allowed` and `specify bundle install <bundle-id>`
         - If your bundle depends on components from non-default catalogs, document those catalog URLs and test installation from a clean project
 
-        **After submitting:** a maintainer applies the `bundle-submission` label during issue triage, which starts the automated catalog validation. You don't need to apply any label or ask for one.
+        **After submitting:** GitHub automatically applies the `triage-must-have` intake verdict. A maintainer separately applies the `bundle-submission` label during issue triage, which starts the automated catalog validation. You don't need to apply any label or ask for one.
 
   - type: input
     id: bundle-id

specify_cli-1.1.2/.github/ISSUE_TEMPLATE/workflow_step_submission.yml

@@ -0,0 +1,254 @@
+name: Workflow Step Type Submission
+description: Submit a custom workflow step package for community catalog intake
+title: "[Workflow Step]: Add "
+labels: ["triage-must-have"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing a workflow step type! This form captures the package, release, and catalog metadata needed for manual community catalog review.
+
+        **Before submitting:**
+        - Review the [Community Workflow Step Types guide](https://github.com/github/spec-kit/blob/main/docs/community/workflow-steps.md)
+        - Publish a package containing root-level `step.yml` and `__init__.py` files
+        - Ensure `step.type_key`, the catalog ID, and the matching `StepBase.type_key` are identical
+        - Create a GitHub release with a versioned step package archive
+        - Provide version-pinned URLs and SHA-256 digests for every catalog-downloaded file
+        - Test the release artifact with `specify workflow step add <step-id> --from <download-url>`
+
+        **After submitting:** GitHub automatically applies only the `triage-must-have` intake verdict. This phase is intake-only: no validation workflow or draft pull request is triggered. Maintainers currently review the metadata manually and, when accepted, update the community catalog through the normal reviewed pull request process.
+
+  - type: input
+    id: step-id
+    attributes:
+      label: Step Type ID
+      description: Exact catalog key and `step.type_key`; it must be one safe path component and must not collide with a built-in step type
+      placeholder: "e.g., deploy"
+    validations:
+      required: true
+
+  - type: input
+    id: step-name
+    attributes:
+      label: Step Type Name
+      description: Human-readable name declared in `step.yml`
+      placeholder: "e.g., Deploy"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: PEP 440-compatible release version; it must match `step.version` in the submitted `step.yml`
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Concise description of the workflow behavior this step type implements
+      placeholder: Deploys the current project to a configured environment and returns the deployment URL
+    validations:
+      required: true
+
+  - type: input
+    id: author
+    attributes:
+      label: Author
+      description: Name or organization declared for the package
+      placeholder: "e.g., Jane Doe or Acme Corp"
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Repository URL
+      description: Public source repository containing the submitted package
+      placeholder: "https://github.com/your-org/spec-kit-step-deploy"
+    validations:
+      required: true
+
+  - type: input
+    id: download-url
+    attributes:
+      label: Download URL
+      description: URL to the versioned `.zip`, `.tar.gz`, or `.tgz` step package archive for this release
+      placeholder: "https://github.com/your-org/spec-kit-step-deploy/releases/download/v1.0.0/deploy-1.0.0.zip"
+    validations:
+      required: true
+
+  - type: input
+    id: step-yml-url
+    attributes:
+      label: step.yml URL
+      description: Exact tag-pinned HTTPS URL used as the catalog `step_yml_url` (or `url`)
+      placeholder: "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/step.yml"
+    validations:
+      required: true
+
+  - type: input
+    id: init-url
+    attributes:
+      label: __init__.py URL
+      description: Exact tag-pinned HTTPS URL used as the catalog `init_url`
+      placeholder: "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/__init__.py"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra-files
+    attributes:
+      label: Extra File URLs
+      description: >-
+        JSON mapping of every additional package-relative file path to its exact tag-pinned HTTPS URL.
+        Paths must use forward slashes, be relative and non-empty, contain no empty, `.` or `..` segments,
+        and must not case-insensitively alias `step.yml` or `__init__.py`. Enter `{}` when there are no extra files.
+      render: json
+      placeholder: |
+        {
+          "helpers.py": "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/helpers.py"
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: file-sha256
+    attributes:
+      label: Per-file SHA-256 Digests
+      description: JSON mapping containing exactly `step.yml`, `__init__.py`, and every Extra File URL path, each with a 64-character hexadecimal SHA-256 digest
+      render: json
+      placeholder: |
+        {
+          "step.yml": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "__init__.py": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "helpers.py": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+        }
+    validations:
+      required: true
+
+  - type: input
+    id: license
+    attributes:
+      label: License
+      description: SPDX license identifier for the package; the repository must include the corresponding license text
+      placeholder: "e.g., MIT or Apache-2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: speckit-compatibility
+    attributes:
+      label: Spec Kit Compatibility
+      description: Spec Kit version constraint tested with this release; the current step catalog does not yet enforce this constraint
+      placeholder: "e.g., >=0.11.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: runtime-dependencies
+    attributes:
+      label: Runtime and Tool Dependencies
+      description: List required Python packages, executables, services, environment variables, or platform constraints; enter `None` when the package has no external dependencies
+      placeholder: |
+        - Python package: requests>=2.32
+        - Executable: kubectl>=1.30
+        - Environment variable: KUBECONFIG
+    validations:
+      required: true
+
+  - type: dropdown
+    id: step-type-count
+    attributes:
+      label: Number of Provided Step Types
+      description: One installed package currently registers exactly one `step.type_key`
+      options:
+        - "1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: step-types-provided
+    attributes:
+      label: Step Type Provided
+      description: Name the single `StepBase` subclass and its exact `type_key`
+      placeholder: "DeployStep — deploy"
+    validations:
+      required: true
+
+  - type: input
+    id: documentation
+    attributes:
+      label: Documentation URL
+      description: Tag-pinned documentation covering configuration, outputs, failure behavior, side effects, and an example workflow
+      placeholder: "https://github.com/your-org/spec-kit-step-deploy/blob/v1.0.0/README.md"
+    validations:
+      required: true
+
+  - type: input
+    id: changelog
+    attributes:
+      label: Changelog URL
+      description: Tag-pinned changelog for this release; leave empty only for an initial release with no prior versions
+      placeholder: "https://github.com/your-org/spec-kit-step-deploy/blob/v1.0.0/CHANGELOG.md"
+
+  - type: textarea
+    id: testing-details
+    attributes:
+      label: Testing Details
+      description: Describe positive and negative configuration tests, execution/status/output tests, and any resume, nested, or concurrent behavior that applies
+      placeholder: |
+        **Tested with:** Spec Kit 0.11.0 on macOS and Ubuntu
+
+        **Evidence:**
+        - Valid configuration completes with the documented outputs
+        - Invalid configuration returns a failed result with an actionable error
+        - Release artifact installs with `specify workflow step add deploy --from ...`
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: attestations
+    attributes:
+      label: Required Attestations
+      description: Confirm the submitted release satisfies the current external step-package contract
+      options:
+        - label: The release artifact contains regular, non-symlink `step.yml` and `__init__.py` files at the package root or under exactly one top-level directory
+          required: true
+        - label: The catalog ID, `step.type_key`, and the matching `StepBase.type_key` are identical and do not collide with a built-in step type
+          required: true
+        - label: The submitted version matches `step.version`, the download URL identifies that versioned release, and every catalog file URL is version-pinned
+          required: true
+        - label: The SHA-256 mapping covers exactly every file the catalog installer downloads
+          required: true
+        - label: The release artifact installs successfully with `specify workflow step add <step-id> --from <download-url>`
+          required: true
+        - label: Runtime and tool dependencies, side effects, configuration, outputs, and failure behavior are documented
+          required: true
+        - label: The repository includes the submitted license and complete source for the released package
+          required: true
+        - label: I understand that custom workflow steps execute Python with the user's privileges and that a community catalog listing is not a code audit, endorsement, or support commitment
+          required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Optional links or notes that help maintainers verify the submitted metadata
+      placeholder: Release notes, compatibility notes, or related issue links
+
+  - type: textarea
+    id: ai-disclosure
+    attributes:
+      label: AI Disclosure
+      description: >-
+        Per our [Contributing guidelines](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit),
+        any AI assistance used to create this issue must be disclosed. If you used AI, name the agent/tool, model(s),
+        settings/mode (reasoning effort; autonomous vs. human-supervised), and extent. Otherwise leave this as "N/A".
+        This does not change how your issue is handled — it just gives maintainers visibility into model/agent usage.
+      value: "N/A"
+    validations:
+      required: true

{specify_cli-1.1.1 → specify_cli-1.1.2}/AGENTS.md

@@ -11,10 +11,18 @@ The toolkit supports multiple AI coding assistants, allowing teams to use their
 ## Adding or Updating CLI Commands
 
 Before adding, updating, or reorganizing Specify CLI commands, read
-[Specify CLI Command Architecture](design/cli.md). It defines command-module
-naming, private command phases, nested command groups, registration ownership,
-mirrored tests, and the rationale for making the CLI structure predictable for
-both humans and coding agents.
+[Shared Command Application Architecture](design/shared.md) and
+[Specify CLI Command Architecture](design/cli.md). They define the shared
+operation boundary, command-module naming, private phases, nested command
+groups, registration ownership, and mirrored tests.
+
+## Adding or Updating MCP Commands
+
+Before adding or changing MCP tools for Specify commands, read
+[Shared Command Application Architecture](design/shared.md) and
+[Specify MCP Command Architecture](design/mcp.md). They define the shared
+operation boundary, typed contracts, explicit inventory, side-effect metadata,
+the local stdio protocol boundary, and mirrored tests.
 
 ## Adding or Updating Agent Integrations
 

{specify_cli-1.1.1 → specify_cli-1.1.2}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 <!-- insert new changelog below this comment -->
 
+## [1.1.2] - 2026-10-07
+
+### Changed
+
+- feat(mcp): add first-class artifact list tool (#4867)
+- fix(workflows): remove the catalog source shown at the listed index (#4870)
+- fix(bundler): resolve the active integration like the canonical reader (#4541)
+- fix(workflows): an interrupted gate prompt must not approve the gate (#4529)
+- [preset] Update Intake Authoring Governance preset to v0.3.7 (#4838)
+- fix(workflows): state the equal-priority tie-break in 'workflow resolve' output (#4542)
+- feat: add --json to preset info and extension info (#4833)
+- feat(bundles): select exact bundle catalog releases (#4849)
+- fix(bundler): treat an explicitly null catalog field as empty, not "None" (#4532)
+- refactor(artifact): extract list operation (#4866)
+- fix(bundler): report a newline-containing version constraint instead of crashing (#4538)
+- feat(mcp): add first-class version tool (#4864)
+- refactor(version): extract shared operation (#4863)
+- feat(workflows): add workflow step submission intake (#4861)
+- docs: define shared CLI and MCP command architecture (#4847)
+- Add AttackTree extension to community catalog (#4859)
+- Update SpecKit Companion extension to v0.24.0 (#4858)
+- Automatically prioritize bundle submissions (#4856)
+- Update SpecAssay preset to v0.5.6 (#4854)
+- chore: release 1.1.1, begin 1.1.2.dev0 development (#4860)
+
 ## [1.1.1] - 2026-10-06
 
 ### Changed

{specify_cli-1.1.1 → specify_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specify-cli
-Version: 1.1.1
+Version: 1.1.2
 Summary: Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD).
 License-File: LICENSE
 Requires-Python: >=3.11

{specify_cli-1.1.1 → specify_cli-1.1.2}/design/cli.md

@@ -1,12 +1,18 @@
 # Specify CLI Command Architecture
 
-This document defines the target structure for multi-command groups in the
-Specify Python CLI. It explains where command handlers, shared infrastructure,
-command-private phases, nested command groups, and their tests belong.
+This document defines the CLI adapter structure for Specify commands. It
+explains where Typer handlers, CLI infrastructure, CLI-private phases, nested
+command groups, and their tests belong.
 
-`src/specify_cli/extensions/` is the reference implementation. Apply this
-design incrementally when adding or refactoring other command groups; do not
-create extra modules merely to make a small command conform visually.
+Every CLI leaf that has another delivery adapter invokes the shared application
+operation defined by
+[Shared Command Application Architecture](shared.md). This document owns the
+CLI surface; it does not redefine semantic validation, orchestration, results,
+warnings, errors, or side effects.
+
+The extension hierarchy supplies the reference command-group shape used in
+this document. Do not create extra modules merely to make a small command
+conform visually.
 
 ## Design goals
 
@@ -22,6 +28,8 @@ The design optimizes for:
   the same file.
 - **Explicit ownership:** shared infrastructure and command-private behavior
   should not be mixed.
+- **Adapter discipline:** CLI modules invoke shared operations rather than
+  becoming the application implementation.
 - **Stable behavior:** structural refactoring must preserve registration,
   output, error handling, compatibility paths, and tests.
 - **Agentic development:** coding agents should be able to infer the relevant
@@ -50,17 +58,24 @@ Only modules representing actual CLI commands use the non-underscored
 
 - The Typer-decorated handler.
 - User-facing arguments and options.
-- Command-specific orchestration.
+- Mapping parsed values into the shared operation request.
+- CLI prompting, progress, rendering, JSON streams, and exit-code mapping.
 - Small helpers used only by that command.
 
+Semantic validation, application orchestration, typed outcomes, warnings,
+expected errors, and side effects belong below the adapter as defined in
+[the shared design](shared.md). A CLI-only command may keep small behavior in
+its command module, but behavior needed by another adapter must first move to a
+shared operation or domain module.
+
 The command function's docstring is user-facing because Typer may display it
 as help text. A module docstring is internal and should identify the command,
 registration path, and any adjacent private implementation modules.
 
 ### Command-private implementation modules
 
-When a command has cohesive phases that are independently understandable or
-testable, use:
+When a CLI adapter has cohesive *CLI-specific* phases that are independently
+understandable or testable, use:
 
 ```text
 _command_<name>_<phase>.py
@@ -69,14 +84,13 @@ _command_<name>_<phase>.py
 For example:
 
 ```text
-command_update.py
-_command_update_discovery.py
-_command_update_artifacts.py
-_command_update_transaction.py
+command_init.py
+_command_init_prompting.py
+_command_init_rendering.py
 ```
 
 The leading underscore marks the module as private implementation. The
-`command_update` portion groups it with the registered handler in searches and
+`command_init` portion groups it with the registered handler in searches and
 file listings. The phase suffix communicates its ownership.
 
 Private phase modules must not register additional CLI commands. The public
@@ -84,11 +98,16 @@ Private phase modules must not register additional CLI commands. The public
 
 Split a command when a phase:
 
+- Is specific to CLI invocation or presentation.
 - Has distinct invariants or failure behavior.
 - Can be tested as a meaningful boundary.
 - Has enough implementation detail to distract from the CLI handler.
 - Is likely to change independently from other phases.
 
+If the phase performs semantic validation, planning, mutation, rollback, or
+other behavior another adapter needs, use `_operation_<name>_<phase>.py`
+instead, following [the shared design](shared.md#naming-and-layout).
+
 Do not split a command solely because it crossed an arbitrary line count.
 Excessive fragmentation makes control flow harder to follow and increases the
 number of files an agent must inspect.
@@ -99,7 +118,8 @@ For a multi-command group, `_commands.py` owns:
 
 - The command group's Typer application.
 - Registration of the group's command modules.
-- Infrastructure genuinely shared by multiple commands or external CLI flows.
+- CLI infrastructure genuinely shared by multiple commands or external CLI
+  flows.
 - Thin compatibility forwarders needed to preserve established import or
   monkeypatch paths.
 
@@ -178,8 +198,9 @@ re-exports the command symbols for compatibility.
 
 Do not create a nested directory for an implementation phase that is not a CLI
 subcommand. For example, an `update/` directory would incorrectly suggest an
-`extension update ...` subcommand group. Use `_command_update_<phase>.py`
-instead.
+`extension update ...` subcommand group. Use `_command_update_<phase>.py` for
+a CLI-private phase and `_operation_update_<phase>.py` for semantic validation,
+planning, mutation, rollback, or other behavior shared with another adapter.
 
 ## Registration
 
@@ -200,6 +221,27 @@ Registration imports should be explicit and ordered consistently. Do not rely
 on filesystem discovery to import arbitrary modules, because command exposure
 should remain reviewable in one place.
 
+## Shared operation invocation
+
+The CLI adapter maps parsed arguments and options into the shared typed request,
+invokes the operation, and renders its outcome.
+
+For project-scoped commands, the adapter supplies the explicit project or
+target directory. When the user omits it, the CLI uses the cwd captured when
+the invocation begins. The shared operation validates and resolves that path;
+neither layer changes process-wide cwd.
+
+The CLI runs with the invoking user's ordinary operating-system permissions.
+It does not construct a shared policy or filesystem runtime. Prompting remains
+CLI-specific:
+
+- `--json`, `--non-interactive`, and local invocation do not imply `force`.
+- External-source trust and overwrite consent remain explicit request values.
+- A prompt may collect consent before constructing or retrying the request, but
+  the adapter does not add consent silently.
+- Network and self-modifying behavior remain those defined by the operation and
+  CLI contract.
+
 ## Test structure
 
 Command-focused tests mirror the source command surface under
@@ -215,23 +257,25 @@ src/specify_cli/extensions/catalog/command_add.py
 tests/specify_cli/extensions/catalog/test_command_add.py
 ```
 
-Private phases use:
+CLI-private phases use:
 
 ```text
-src/specify_cli/extensions/_command_update_discovery.py
-tests/specify_cli/extensions/test_command_update_discovery.py
-
-src/specify_cli/extensions/_command_update_artifacts.py
-tests/specify_cli/extensions/test_command_update_artifacts.py
-
-src/specify_cli/extensions/_command_update_transaction.py
-tests/specify_cli/extensions/test_command_update_transaction.py
+src/specify_cli/_command_init_prompting.py
+tests/specify_cli/test_command_init_prompting.py
 ```
 
 The primary `test_command_<name>.py` suite verifies the public command surface.
 Phase-specific suites verify detailed invariants without obscuring the primary
 command behavior.
 
+CLI adapter tests verify explicit targets outside the launch directory and the
+rule that machine modes do not add force, trust, or destructive consent.
+
+Shared operation and phase tests use `test_operation_<name>.py` and
+`test_operation_<name>_<phase>.py` as defined in
+[the shared testing structure](shared.md#testing-structure). They do not move
+under `test_command_*.py` merely because the CLI is one caller.
+
 Domain source remains in the parent package's `__init__.py` or a focused
 domain module without the `command_` prefix. Its mirrored tests use the domain
 subject name, for example:
@@ -290,7 +334,8 @@ must remain represented. A matching total alone does not prove preservation.
 
 ## Reference layout
 
-The extension command group currently demonstrates the complete pattern:
+An extension command group using the shared application boundary has this
+shape:
 
 ```text
 src/specify_cli/extensions/
@@ -305,9 +350,10 @@ src/specify_cli/extensions/
 ├── command_search.py
 ├── command_set_priority.py
 ├── command_update.py
-├── _command_update_discovery.py
-├── _command_update_artifacts.py
-├── _command_update_transaction.py
+├── _operation_update.py
+├── _operation_update_discovery.py
+├── _operation_update_artifacts.py
+├── _operation_update_transaction.py
 └── catalog/
     ├── __init__.py
     ├── _helpers.py
@@ -319,10 +365,11 @@ src/specify_cli/extensions/
 The update command illustrates the distinction:
 
 - `command_update.py` is the registered CLI adapter.
-- `_command_update_discovery.py` determines available updates.
-- `_command_update_artifacts.py` prepares and validates update archives.
-- `_command_update_transaction.py` owns backup, installation, rollback, and
-  cleanup behavior.
+- `_operation_update.py` is the shared application entry point.
+- `_operation_update_discovery.py` determines available updates.
+- `_operation_update_artifacts.py` prepares and validates update archives.
+- `_operation_update_transaction.py` owns backup, installation, rollback, and
+  cleanup behavior for every adapter.
 
 ## Decision guide
 
@@ -331,9 +378,11 @@ When deciding where code belongs:
 | Question | Location |
 |---|---|
 | Does it define a real CLI command? | `command_<name>.py` |
-| Is it used only by one small command? | That command module |
-| Is it a cohesive private phase of one complex command? | `_command_<name>_<phase>.py` |
-| Is it shared by multiple commands or an external CLI flow? | `_commands.py` or a focused shared module |
+| Is it a small CLI-only mapping or rendering helper? | That command module |
+| Is it a cohesive CLI-only phase? | `_command_<name>_<phase>.py` |
+| Does it define semantic validation or orchestration for an operation? | Existing domain module or `_operation_<name>.py` |
+| Is it a cohesive shared operation phase? | `_operation_<name>_<phase>.py` |
+| Is it CLI infrastructure shared by multiple command adapters? | `_commands.py` or a focused CLI helper |
 | Does it define a nested CLI namespace? | A directory matching that namespace |
 | Is it shared only by commands in a nested namespace? | The nested package's `_helpers.py` |
 | Is it domain behavior independent of the CLI? | The package domain modules, not command modules |
@@ -346,6 +395,10 @@ Avoid:
 - Naming a private implementation module `command_*.py`.
 - Creating nested directories that do not correspond to CLI namespaces.
 - Creating `_commands.py` files only for visual symmetry.
+- Keeping semantic validation, orchestration, or side effects in a CLI adapter
+  when another adapter exposes the same logical operation.
+- Calling or parsing another delivery adapter instead of invoking the shared
+  operation.
 - Moving command-private helpers into shared infrastructure preemptively.
 - Duplicating fixtures or helpers to make tests appear more mirrored.
 - Splitting a linear function into many files without cohesive phase
@@ -359,9 +412,18 @@ For a new or refactored command:
 
 - [ ] The CLI path maps predictably to a `command_<name>.py` module.
 - [ ] Only the real command module registers a handler.
-- [ ] Private phase modules use `_command_<name>_<phase>.py`.
+- [ ] The owning hierarchy records exactly one MCP inventory disposition for
+      the CLI leaf, including when it is unavailable or excluded.
+- [ ] If another adapter exposes the operation, the CLI adapter maps into the
+      shared operation defined by `design/shared.md`.
+- [ ] For a multi-adapter operation, semantic validation, orchestration, and
+      side effects are below the CLI adapter.
+- [ ] When a shared request exists, project and target directories map into it
+      explicitly.
+- [ ] CLI-private phase modules use `_command_<name>_<phase>.py`; shared phases
+      use `_operation_<name>_<phase>.py`.
 - [ ] `_commands.py` contains only group infrastructure and genuinely shared
-      behavior.
+      CLI behavior.
 - [ ] Nested directories correspond to real CLI namespaces.
 - [ ] Command tests mirror the source structure.
 - [ ] Domain and cross-domain tests remain in their appropriate suites.