Plan MIL-007 and UC-002; AGPL-3.0 default only for a public GitHub project

- MIL-006: the AGPL-3.0 default needs GitHub and a public project - MIL-007: fetch the framework's own submodules (qc); start through a command link; README usage - UC-002 with SSD, DM, OC, SD and DCD; US-001.07 and US-002 - Reconcile the project DM, DCD, dictionary, use case diagram and traceability matrix - Review records RC-022 to RC-028
2026-10-07 12:30:58 +08:00
parent 5b66eff809
commit 1cd27f77ed
29 changed files with 1143 additions and 85 deletions
@@ -0,0 +1,74 @@
+# Start the script as a global command
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | UC-002 |
+| CrossReference | [UCD-001], [US-001], [SA-001], [BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S02 | Initial version | pending |
+
+---
+
+**Format:** Fully Dressed
+
+## Fully Dressed
+
+- **Scope:** RepoFoundry (`create-project.sh`)
+- **Level:** user-goal
+- **Primary Actor:** Maintainer (S01 or S02; one person holds both roles for now)
+- **Stakeholders and Interests:**
+  - S01 — the script is started by name from any folder, and the new project lands where S01 stands
+  - S02 — starting through a link never reads or writes outside the checkout and the current folder
+  - S03 — the README says exactly how to make the command global
+- **Preconditions:**
+  - The checkout of RepoFoundry exists and holds `config.env` and `.env` as described in the README, or the Maintainer points to them with `--config` and `--env`.
+  - A folder that is on the shell's `PATH` exists and the Maintainer may write to it.
+- **Postconditions (success guarantee):**
+  - A command link exists in a `PATH` folder and leads to the script in the checkout.
+  - The Maintainer started the script by that name from a working folder, and use case [UC-001] ran with that working folder as its base: the default directory of the new project is `./<name>` under it.
+  - Nothing was written outside the working folder and the new project.
+
+### Main Success Scenario
+
+1. The Maintainer makes the script reachable by name: creates a command link in a `PATH` folder that leads to `src/create-project.sh` in the checkout (the README gives the command).
+2. The Maintainer opens a shell in the folder in which the new project is to be created (the working folder).
+3. The Maintainer starts the script by the name of the command link.
+4. The system follows the command link to the checkout, loads its own files from there, and reads `config.env` and `.env` from the checkout, or from the files named by `--config` and `--env`.
+5. The system runs [UC-001] (`<<include>>`) with the working folder as the base of the default directory of the new project.
+6. The system reports a summary that names the full path of the new project.
+
+### Extensions (Alternative / Exception Flows)
+
+- 1a. The `PATH` folder is not writable, or not on `PATH`:
+  1. The README names the other choices (a folder the Maintainer owns and adds to `PATH`, or an alias); the system is not involved.
+- 3a. The command link is broken (the checkout was moved or removed):
+  1. The shell reports that the command cannot run; the README says how to recreate the link.
+- 4a. The checkout's own files cannot be found from the link target:
+  1. The system stops before any change and names the folder it looked in.
+- 4b. `config.env` or `.env` is not found:
+  1. The system stops before any change, names the path it looked in and says that `--config` and `--env` can point elsewhere.
+
+### Special Requirements / Business Rules
+
+| Step | Rule |
+| --- | --- |
+| 1 | The command link is made by the Maintainer with the shell, not by the script; the script never edits `PATH`, a shell profile or a system folder |
+| 4 | The system finds its own files by following the command link, however many links lie on the way, on every supported platform |
+| 4 | `config.env` and `.env` are read from the checkout, never from the working folder, unless `--config` and `--env` name them |
+| 5 | The base of the default directory is the working folder, never the checkout |
+| 3 to 6 | Behaviour, prompts and summary are the same as when the script is started by its path from the checkout |
+
+### Open Issues
+
+- The README example is tested on Linux, macOS and Git Bash on Windows (MIL-007 criterion 6).
+
+---
+
+[UCD-001]: ../use-case-diagram.md
+[US-001]: ../user-stories.md
+[SA-001]: ../stakeholder-analysis.md
+[BC-001]: ../business-case.md