Add planning baseline: BC, SA, PP and two gateways

Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14
2026-10-04 21:38:09 +08:00
parent 52febca25e
commit 1d35410b8d
123 changed files with 5978 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Shell conventions (bash)
+
+## Standard base
+
+Bash 4 or later, POSIX `test` semantics through `[[ ]]`. Start every script
+with `#!/usr/bin/env bash` and `set -euo pipefail`. State the bash version and
+the external tools it needs in the header comment.
+
+## Naming
+
+| Element | Convention | Example |
+| --- | --- | --- |
+| Script file | `kebab-case.sh`, executable | `check-plan.sh`, `new-artifact.sh` |
+| Function | `snake_case`, a verb | `read_registry`, `die` |
+| Local variable, parameter | `snake_case`, declared with `local` | `msgfile`, `changed` |
+| Constant, environment variable | `UPPER_SNAKE` | `PLAN_GATE`, `PROJECT_ROOT` |
+| Boolean | `is_` / `has_` prefix, value `0` or `1` | `is_enabled=1` |
+
+- Name a script and its functions by what they do, not how.
+- Do not shadow a command with a function of the same name.
+
+## Formatting
+
+- 2 spaces, no tabs. One command per line; `then` and `do` on the same line as
+  `if` and `for`. Keep lines near 80 characters; break long pipelines at `|`.
+- Format with `shfmt -i 2 -ci`; lint with `shellcheck`. Commit the project's
+  `.editorconfig` or `.shellcheckrc` with the code.
+
+## Language rules
+
+- **Quote every expansion** (`"$var"`, `"${arr[@]}"`); use arrays, not
+  space-separated strings, for lists. Use `[[ ]]`, not `[ ]`, and `$(...)`,
+  not backticks.
+- Declare function variables `local`; no globals except constants.
+- Parse options with `case` and `shift`, check required arguments with
+  `"${1:?usage: ...}"`, and print a usage line on bad input.
+- Read input with `read -r`; iterate files with globs or `find -print0`, never
+  by parsing `ls`.
+- Use `mktemp` for temporary files and remove them with `trap ... EXIT`; never
+  a fixed `/tmp` name.
+
+## Errors and exit codes
+
+- Errors go to standard error, start with `error:`, say what is wrong and what
+  to do, and end the script with a non-zero exit code (`die` helper).
+- `0` is success, `1` a failed check or bad input, `2` a usage error; document
+  any other code in the header.
+- Never swallow a failure with `|| true` without a comment that says why.
+
+## Safety
+
+- A script that changes state outside its own directory defaults to a dry run
+  or asks for an explicit flag (`--apply`, `--force`); say so in the header.
+- Never echo a token or password, put one on a command line, or commit one;
+  read secrets from the environment or a gitignored file.
+- Do not `eval` input; do not build a command from unvalidated text.
+
+## Tools
+
+Formatter `shfmt`, linter `shellcheck`, syntax check `bash -n`. These are the
+recommended tools, not a pipeline: enforcing them in CI is outside this
+framework's scope.