torrust · josecelano · Sep 9, 2026 · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026
@@ -37,6 +37,9 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
    - Verify that the spec's progress notes or task list reflect the current state.
    - If the spec is out of date, stop and ask the caller to update it before proceeding.
      Do not commit with a stale spec.
+   - For a completion commit, verify that required manual verification is backed
+     by issue-local `manual-verification-evidence.md`, not only test output or a
+     disposable verification script. See [verification types](../../docs/testing.md#verification-types).
 2. **Validate the branch name.** If the current branch name starts with an issue number prefix
    (e.g., `42-some-description`), verify that `docs/issues/open/` contains a matching spec
    (file or directory starting with that number). If no match is found:

@@ -36,6 +36,10 @@ Reference: [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.ht
   - `.github/skills/dev/testing/write-unit-test/SKILL.md` — test naming and Arrange/Act/Assert pattern.
   - `.github/skills/dev/rust-code-quality/handle-errors-in-code/SKILL.md` — error handling.
   - `.github/skills/dev/git-workflow/commit-changes/SKILL.md` — commit conventions.
+- Follow the [verification types](../../docs/testing.md#verification-types): keep
+  durable automatic behavior checks in Rust, execute manual verification against
+  the finished artifact, and retain a disposable verification script only with
+  the issue-specification rationale required by the issue template.
 
 ### ADR Discoverability Convention
 
@@ -136,6 +140,11 @@ panic-safe cleanup, explicitly review collaborator responsibilities, resource
 ownership across normal and drop-path cleanup, deadline coverage, and separation
 between passive infrastructure and domain interpretation.
 
+Before independent verification, perform the issue's manual scenarios against
+the finished artifact and record actual commands, output, relevant logs, and
+conclusions in issue-local `manual-verification-evidence.md`. Automated test
+output is not a substitute for this evidence.
+
 ### Step 6 — Request Independent Verification
 
 When all steps are complete and tests are passing, invoke the **Task Reviewer**

@@ -45,6 +45,11 @@ You plan the work. You do not perform implementation changes yourself.
      fixtures
    - A post-vertical-slice design review when those concerns make the initial
      implementation likely to reveal material design constraints
+   - Human-oriented manual verification scenarios whose actual evidence will be
+     recorded in issue-local `manual-verification-evidence.md`
+   - A rationale, issue-local path, and removal/retention owner for any proposed
+     disposable verification script; Python also needs a case-specific reason
+     Rust is unsuitable
 4. Classify the issue as `task`, `bug`, or `feature`, with one-sentence justification.
 5. Select an implementation strategy and explain why it fits.
 6. Decompose into minimal, independently verifiable tasks.
@@ -67,6 +72,8 @@ evidence-based completion review. It must either create an issue-local
 `implementation-retrospective.md` for reusable lessons or record why no
 retrospective was needed in the issue progress log.
 
+Follow the canonical [verification types](../../docs/testing.md#verification-types).
+
 ## Output Format
 
 When finishing a planning task, respond in this order:

@@ -48,8 +48,12 @@ pull request is opened.
    lessons, material design changes, or meaningful deviations from the original
    plan. Otherwise require a concise issue progress-log entry explaining why no
    retrospective was needed.
-6. Report findings with concrete remediation guidance for all `FAIL` or `PENDING` items.
-7. Return an overall status:
+6. Confirm that mandatory manual scenarios were executed against the finished
+   artifact and recorded in `manual-verification-evidence.md` with actual
+   commands or interactions, observed output, relevant logs, and conclusions.
+   Do not accept automated test or disposable-script output as manual evidence.
+7. Report findings with concrete remediation guidance for all `FAIL` or `PENDING` items.
+8. Return an overall status:
    - `REVIEW PASSED` when all required criteria pass and no blocking issues remain.
    - `REVIEW FAILED` when any required criterion fails or blocking issues remain.
 

@@ -51,6 +51,21 @@ Loading extra configuration from default configuration file: `./share/default/co
 **Default database**: SQLite3  
 **Default configuration file**: `./share/default/config/tracker.development.sqlite3.toml`
 
+## Selecting a Configuration Source
+
+The main `torrust-tracker` binary accepts an explicit file path:
+
+```bash
+cargo run --bin torrust-tracker -- --config-toml-path ./storage/tracker/etc/tracker.toml
+```
+
+Base-source precedence is `--config-toml-path` >
+`TORRUST_TRACKER_CONFIG_TOML` > `TORRUST_TRACKER_CONFIG_TOML_PATH` > the default
+development file. `TORRUST_TRACKER_CONFIG_OVERRIDE_*` values are merged over the
+selected base source. A CLI path is resolved exactly from the current working
+directory; it must name a readable TOML file. Environment sources remain
+supported for compatibility and deployment use.
+
 ## Default Services
 
 By default, the development configuration starts:
@@ -146,7 +161,7 @@ openssl req -x509 -out .tmp/localhost.crt -keyout .tmp/localhost.key \
 1. Start the tracker with the temporary configuration:
 
 ```bash
-TORRUST_TRACKER_CONFIG_TOML_PATH="$PWD/.tmp/local-tls.toml" cargo run --bin torrust-tracker
+cargo run --bin torrust-tracker -- --config-toml-path "$PWD/.tmp/local-tls.toml"
 ```
 
 Read the startup log to obtain the final port assigned to a `:0` binding.

@@ -9,6 +9,7 @@ metadata:
       - docs/templates/ISSUE.md
       - docs/templates/EPIC.md
       - docs/templates/IMPLEMENTATION-RETROSPECTIVE.md
+      - docs/templates/MANUAL-VERIFICATION-EVIDENCE.md
 ---
 
 # Creating Issues
@@ -122,7 +123,8 @@ explicitly during implementation:
 The draft must also include a verification policy that is explicit and enforceable:
 
 - Automatic checks to run after implementation (`linter all`, relevant tests, pre-push checks when applicable)
-- Manual verification scenarios with status + evidence tracking (mandatory)
+- Mandatory manual verification scenarios that describe real human-oriented feature use or bug reproduction, with status tracked in the spec and actual commands, output, and relevant logs recorded in issue-local `manual-verification-evidence.md`
+- When a disposable verification script is proposed, its issue-local path, concrete automatic-test rationale, removal/retention owner, and, for Python, why Rust is unsuitable for that script
 - A post-implementation acceptance criteria review step
 - An evidence-based implementation completion review that records reusable
   lessons, material design changes, or deviations from the plan. Use

@@ -0,0 +1,92 @@
+---
+name: process-pr-review-feedback
+description: Process pull-request reviews that may contain multiple independent findings from maintainers, collaborators, or agents acting for them. Use when asked to address reviewer feedback, maintainer PR comments, contributor review summaries, or non-Copilot suggestions.
+metadata:
+  author: torrust
+  version: "1.0"
+  semantic-links:
+    related-artifacts:
+      - docs/pr-review-feedback/README.md
+      - docs/templates/PR-REVIEW-FEEDBACK-TEMPLATE.md
+      - .github/skills/dev/pr-reviews/fetch-review-threads/SKILL.md
+      - .github/skills/dev/pr-reviews/resolve-review-threads/SKILL.md
+---
+
+# Processing PR Review Feedback
+
+Use this workflow for review feedback from one or more maintainers,
+collaborators, or agents acting for them. Use `process-copilot-suggestions` for
+Copilot-generated review threads instead.
+
+## Model
+
+A submitted **review** and an inline **review thread** are different GitHub
+resources:
+
+- A review has a numeric review ID, state, body, reviewed commit, and URL. Its
+  body may contain multiple findings. GitHub has no resolved state for it.
+- An inline review thread has a GraphQL node ID and can be replied to and
+  resolved. A reviewer can create these just as Copilot can.
+
+Create `docs/pr-review-feedback/pr-<PR_NUMBER>-review-feedback.md` from
+`docs/templates/PR-REVIEW-FEEDBACK-TEMPLATE.md`. Treat its review-response
+state as the durable completion status for a review-level summary.
+
+## Procedure
+
+1. **Fetch reviews and threads.** Query submitted reviews and inline comments
+   by review ID. Fetch all review threads separately, including their IDs,
+   author, paths, bodies, and resolved state. The GraphQL thread query is the
+   authority: the REST per-review `comments` endpoint can under-report inline
+   comments. Do not assume review-comment IDs are thread IDs.
+2. **Create the audit record.** Add one row per review. Decompose each review
+   body and inline comment into one row per independent finding, with a decision
+   of `ACTION`, `NO_ACTION`, or `FOLLOW_UP`.
+3. **Implement each action independently.** For every `ACTION`, make the
+   smallest correct change, run relevant validation, and create a separate GPG
+   signed Conventional Commit. Do not combine feature fixes with this workflow's
+   docs, template, or audit records.
+4. **Handle inline suggestions.** After the relevant action/no-action decision
+   is complete, reply directly on each inline thread. Record the reply URL,
+   then resolve the thread using `resolve-review-threads`. Do not resolve before
+   replying.
+5. **Reply to the review summary.** Once all findings from one submitted review
+   are done or explicitly deferred, post one consolidated PR conversation
+   comment. Include the review ID, each finding's outcome, associated commit,
+   validation, and any follow-up. Store that comment URL in the review row.
+6. **Update progressively.** Update the audit record immediately after each
+   commit, PR reply, or resolution. Preserve the historical GitHub review state
+   (including `DISMISSED`) and record the current disposition in the audit
+   fields.
+7. **Complete.** Verify every finding status and every inline-thread state from
+   the current PR. Commit the workflow/audit documentation separately with a
+   signed `docs(review): ...` commit.
+
+## GitHub CLI Queries
+
+Fetch an individual review and its review-specific inline comments:
+
+```bash
+gh api repos/torrust/torrust-tracker/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>
+gh api repos/torrust/torrust-tracker/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>/comments?per_page=100
+```
+
+Fetch all review threads with GraphQL before resolving inline feedback. Use the
+repository `fetch-review-threads` skill for the supported scripts and query
+shape.
+
+Post a consolidated response as a PR conversation comment:
+
+```bash
+gh pr comment <PR_NUMBER> --repo torrust/torrust-tracker --body-file <FILE>
+```
+
+## Completion Checklist
+
+- [ ] Reviews and their inline comments fetched by review ID
+- [ ] Audit record has one row per review and one row per independent finding
+- [ ] Each action validated and committed independently
+- [ ] Each inline thread replied to and resolved, with reply URL recorded
+- [ ] Each review summary has one consolidated PR response, with URL recorded
+- [ ] Historical review states and current audit statuses are both recorded
+- [ ] Workflow/audit documentation committed separately from product fixes
@@ -44,6 +44,14 @@ Reference: <https://testdesiderata.com/> and Kent Beck's original papers on
 
 The repository prefers high maintainable automated coverage.
 
+Tracked test code is Rust. A temporary issue-local verification script is not a
+test: it requires an issue-specification rationale explaining why it is better
+than a maintained Rust automatic test and, when written in Python, why Rust is
+unsuitable. Promote durable behavioral checks into Rust tests when practical.
+Manual verification is separate real use of the finished artifact; record its
+actual evidence in `manual-verification-evidence.md` as defined by
+[`docs/testing.md`](../../../../../docs/testing.md#verification-types).
+
 Practical priority order:
 
 1. Unit tests first (fast, deterministic, low maintenance)

diff --git a/Cargo.toml b/Cargo.toml
@@ -50,6 +50,10 @@ path = "tests/banning/udp_shared_connection_id_error_limit_reverse_order.rs"
 name = "lifecycle-signals"
 path = "tests/lifecycle/signals.rs"
 
+[[test]]
+name = "cli-configuration"
+path = "tests/configuration/cli_configuration.rs"
+
 [lints]
 workspace = true
 

diff --git a/README.md b/README.md
@@ -145,17 +145,26 @@ cp ./share/default/config/tracker.development.sqlite3.toml ./storage/tracker/etc
 # Customize the tracker configuration (for example):
 vim ./storage/tracker/etc/tracker.toml
 
-# Run the tracker with the updated configuration:
-TORRUST_TRACKER_CONFIG_TOML_PATH="./storage/tracker/etc/tracker.toml" cargo run
+# Run the main tracker binary with the updated configuration:
+cargo run --bin torrust-tracker -- --config-toml-path ./storage/tracker/etc/tracker.toml
 ```
 
-_Optionally, you may choose to supply the entire configuration as an environmental variable:_
+_Alternatively, you may choose to select the configuration file or supply its
+complete contents with environment variables:_
 
 ```sh
 # Use a configuration supplied on an environmental variable:
 TORRUST_TRACKER_CONFIG_TOML=$(cat "./storage/tracker/etc/tracker.toml") cargo run
 ```
 
+Base-source precedence is `--config-toml-path` >
+`TORRUST_TRACKER_CONFIG_TOML` > `TORRUST_TRACKER_CONFIG_TOML_PATH` > the default
+development file. `TORRUST_TRACKER_CONFIG_OVERRIDE_*` values override matching
+values in the selected base source. The main binary resolves a CLI path exactly
+from its current working directory; it rejects missing, unreadable, non-file,
+or invalid TOML sources at startup. The environment path remains supported with
+its legacy resolution behavior.
+
 _For deployment, you **should** override the `api_admin_token` by using an environmental variable:_
 
 ```sh

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -36,6 +36,7 @@ For the full project context see the [root AGENTS.md](../AGENTS.md).
 | `issues/`                                                                                 | Issue specification documents linked to GitHub issues                                                   |
 | `refactor-plans/`                                                                         | Refactor plans (same lifecycle as issue specs)                                                          |
 | `copilot-pr-reviews/`                                                                     | Copilot PR review records and suggestion threads                                                        |
+| `pr-review-feedback/`                                                                     | PR review feedback audit records                                                                        |
 | `skills/`                                                                                 | Internal conventions used by humans and AI agents                                                       |
 | `testing/`                                                                                | Durable testing guidance and test-design refactoring pattern catalog                                    |
 | `templates/`                                                                              | Canonical document templates (ADR, agent review reports, EPIC, issue, refactor plan, security analysis) |

diff --git a/docs/benchmarking.md b/docs/benchmarking.md
@@ -57,8 +57,8 @@ bind_address = "0.0.0.0:3000"
 Start the tracker:
 
 ```console
-TORRUST_TRACKER_CONFIG_TOML_PATH="./share/default/config/tracker.udp.benchmarking.toml" \
-  ./target/release/torrust-tracker
+./target/release/torrust-tracker \
+  --config-toml-path ./share/default/config/tracker.udp.benchmarking.toml
 ```
 
 ### 3. Build the aquatic UDP load test

diff --git a/docs/containers.md b/docs/containers.md
@@ -147,9 +147,27 @@ podman run -it docker.io/torrust-tracker:debug
 
 ### Arguments
 
-The arguments need to be placed before the image tag. i.e.
+Docker or Podman runtime arguments are placed before the image tag. Because
+tracker arguments after the image tag replace the image `CMD`, include the
+tracker binary before its command-line arguments.
 
-`run [arguments] torrust-tracker:release`
+`run [runtime arguments] torrust-tracker:release /usr/bin/torrust-tracker [tracker arguments]`
+
+#### Tracker Command Options
+
+The main tracker binary accepts `-c` / `--config-toml-path <PATH>`. The selected
+path is evaluated inside the container, so use an in-container mounted path:
+
+```sh
+docker run -it torrust/tracker:latest \
+  /usr/bin/torrust-tracker \
+  --config-toml-path /etc/torrust/tracker/tracker.toml
+```
+
+This option overrides the image's `TORRUST_TRACKER_CONFIG_TOML_PATH` and any
+supplied `TORRUST_TRACKER_CONFIG_TOML` base source. Per-value
+`TORRUST_TRACKER_CONFIG_OVERRIDE_*` variables still override matching values in
+the CLI-selected file.
 
 #### Environmental Variables
 

diff --git a/docs/copilot-pr-reviews/pr-2178-copilot-suggestions.md b/docs/copilot-pr-reviews/pr-2178-copilot-suggestions.md
@@ -0,0 +1,30 @@
+---
+semantic-links:
+  skill-links:
+    - process-copilot-suggestions
+  related-artifacts:
+    - docs/templates/COPILOT-SUGGESTIONS-TEMPLATE.md
+    - .github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md
+---
+
+<!-- cspell:disable -->
+
+# PR #2178 Copilot Suggestions Tracking
+
+Source: Copilot PR review threads for [PR #2178](https://github.com/torrust/torrust-tracker/pull/2178).
+
+## Processing Log
+
+- 2026-09-09 09:00 UTC - Created this audit for the two Copilot threads that were previously handled inline. Both were resolved before this record was added; their decision, fix, and reply URLs were verified from the current PR thread state.
+
+## Suggestions
+
+| #   | Thread ID               | Path                                | URL                                                                                   | Suggestion Summary                                                                | Decision                                                               | Reply URL                                                                            | Status | Thread State |
+| --- | ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------ | ------------ |
+| 1   | `PRRT_kwDOGp2yqc6gYHrC` | `packages/configuration/src/lib.rs` | [thread](https://github.com/torrust/torrust-tracker/pull/2178#discussion_r3961389301) | Explicit-file log said “extra configuration,” implying additive source selection. | `ACTION`: renamed it to “base configuration” in `8e9c0b68`.            | [reply](https://github.com/torrust/torrust-tracker/pull/2178#discussion_r3965743966) | `DONE` | `RESOLVED`   |
+| 2   | `PRRT_kwDOGp2yqc6gYHrU` | `packages/configuration/src/lib.rs` | [thread](https://github.com/torrust/torrust-tracker/pull/2178#discussion_r3961389339) | Explicit-file reader accepted `&PathBuf` rather than the more general `&Path`.    | `ACTION`: accepts `&Path` and owns paths only in errors in `8e9c0b68`. | [reply](https://github.com/torrust/torrust-tracker/pull/2178#discussion_r3965744330) | `DONE` | `RESOLVED`   |
+
+## Notes
+
+- Commit `8e9c0b68` passed configuration tests, focused Clippy, formatting, and the required pre-commit gate before the threads were resolved.
+- This late record corrects the missing audit reference identified by PR review feedback; it does not claim the original thread handling occurred after this file was created.