Describe the solution you'd like

mantra allows to set an optional repository in addition to the branch,
Therefore, the status command should allow to set a repository name.

Not all requirements can be traced.
To still allow some form of tracing, it should be possible to annotate requirements that they require manual verification.

A possible approach would be to add a manual flag to the references list instead of the ref-cnt.
This would also integrate well with the general ref-cnt approach.

Example:

# my_req: Some Title

**References:**

- in branch main: manual

At some point, it might be possible that references are added for manually verified requirements.
In that case, the manual flag must not be removed, because manual verification might still be necessary,
but the ref-cnt should be added after the flag to indicate that references in code exist.

Example:

# my_req: Some Title

**References:**

- in branch main: manual + 1

mantra should provide a command to check if all references and wiki-links are pointing to existing requirements.
It should also be able to set a strict mode that ensures that no deprecated requirement is referenced.

This command should provide an option to summarize the findings.

Describe the solution you'd like

Add a project ID before the branch in reference entries, because multiple repositories might use the same wiki.

Example:

„- in project in branch main: 2“

The wiki in GitHub allows a custom sidebar that is displayed on all pages.
mantra should show a quick summary about the last synchronisation that was done.

Example.

### **REQ-Referencing Overview:**

**Last update:** n.a.\
**Branch:** n.a.\
**Commit:** n.a.

Describe your feature request

Is your feature request related to other issues/PRs?

Check report introduced with PR #14

Describe the solution you'd like

The output should be added automatically as comment for new PRs.
This provides a nice overview of changed references.

mantra must have a command to automatically update ref-cnts in the wiki.
Updating these cnts manually would not be feasible.

Preferably a GitHub action should be available that updates the wiki on every push to the branch the action is set to.
However, it should also be possible to synchronise ref-cnts for local projects and wikis.

Describe your feature request

Is your feature request related to other issues/PRs?

Created as extension to issues #1 and #6

Describe the solution you'd like

Being able to run mantra commands in CI-pipelines like GitHub workflows.

Additional context

It should be possible to not just run mantra commands in GitHub workflows.

Having a report that shows what requirements are implemented/active, is useful to attach it to releases,
so customers and product owners see what features/requirements are active.

Because requirements may be in deeply nested hierarchies, it is probably better to flatten all requirements at file level.
Meaning heading levels of requirements remains unchanged, and all active requirements are added sequentially in the order files and folders are traversed.

Note: This flattened view requires links to be updated.

Describe the solution you'd like

Allow to set suspended as state in references lists similar to deprecated.
This state is needed to mark requirements as "we do not work on it for now".

Example:

1. Requirement req gets implemented in a feature branch F
2. This branch F is displayed in the references list
3. No other branch implements req, which is intentional, because req is not yet stable enough
4. In the status output, req is shown as ready for all other branches

Displaying req as being ready to be implemented in other branches is misleading.
However, it is not possible to remove the ID, because F references req.

With suspended, it is possible to mark entries in the references list to not treat the requirement as active, even though it has 0 references and is not set to deprecated.
deprecated is also not an alternative, because it means that a requirement was implemented for this entry, but is not anymore.

suspended now leaves it open if a requirement will be implemented for an entry, or directly declined.

Example:

**References:**

- in branch some-feat: 1
- in branch main: suspended

Describe alternatives you've considered

Calling it ignored instead of suspended, but suspended felt better.

Some requirements may be manually traced (see issue #4 ).
To help with manual verification of these requirements, mantra should generate a checklist
that lists all these requirements and their content, and adds an open verified checkmark to each requirement.

This checklist could be used to ensure all manual traces where verified before a release.

The referencing syntax [req:my_req_id] is intentionally designed to be similar to markdown hyperlinks, to allow URLs to be added to point to the entries in the wiki (turning references to wiki-links).
However, adding and updating these links is not feasible.
Therefore, mantra should provide a command to automatically set and update wiki-links to requirement references.

mantra should also offer a GitHub action for this that creates a PR with the updated links.
Directly pushing changes is not wanted, because these changes affect the implementation, and therefore have a higher risk to break something.

At some point, requirements will be deprecated.
This must also be supported by mantra.

A possible approach could be similar to the one for manual tracing (#4 ):

Manually set a deprecated flag per branch in the references list to indicate that the requirement is deprecated in this branch.
Having the flag per branch is useful, because requirements may still be active in e.g. stable branches.

mantra must ensure that deprecated requirements are not referenced in code, meaning the ref-cnt must be 0.

Example:

# my_req: Some Title

**References:**

- in branch main: deprecated
- in branch stable: 1

Deprecated by [req:new_req] since version v1.3.0.

Seeing what ref-cnt changes would be made, when merging code changes, helps with PR reviews,
because changed counters give a quick overview of what changed.

The report should have the option to show the ref-cnt changes in a compact form for a better overview.

Example:

Summary:

- 34 requirements referenced in code
- 4 more requirements are now active
- 16 new references added in code
- Overall reference count increased by 10

Checks:

- No deprecated requirement referenced
- All links to wiki are reachable

New active requirements:

- new_reg: 4 (2 direct)
- new_reg.sub: 2
- other_req: 7
- another_req: 3

Decreased references:

- some_old_reg: 6 -> 2
- some_qa_reg: 10 -> 5

Increased references:

- my_req: 4 -> 7

Describe the solution you'd like

mantra should not search for references in folders/files excluded by .gitignore.
mantra should also look for a ".mantraignore" file, which should be used in addition to the .gitignore file.

Note: Folders/Files ignored in .gitignore cannot be "unignored" by ".mantraignore", because most commands are run in workflows, where only folders/files not ignored by .gitignore are present.

Describe the solution you'd like

Require backticks ` around IDs in the wiki for requirement headings.

Example:

# `req_id`: This is a new requirement

Description...

This prevents headings using : in their content from being wrongfully detected as an ID.

Additional context

The verbatim wrapper also prevents IDs from being formatted as italic
if multiple underscores are part of an ID.

Is your feature request related to other issues/PRs?

Related feature request: #6

Describe the solution you'd like

Do not add wiki-links automatically in code.
Many URLs are very long, which is distracting in code.

It would be better to offer an IDE plugin that can link to wiki sections when hovering over a reference.

Describe alternatives you've considered

Using some web-service to shorten the URL.
Something like mantra.org/<some random id>, where the random ID redirects to the wiki section.
This solution would require a web-service, and automatic synchronisation between these random IDs and wiki sections.

In comparison, the IDE plugin seems more practical

Additional context

e.g. of a typical URL in mantra: https://github.com/mhatzl/mantra/wiki/5-REQ-req_id.sub_req_id#req_idsub_req_id-sub-requirements-for-high-level-requirements

As one can see, this URL is already long, and mantra is a small project.

Describe the solution you'd like

Show an overview of the requirement states in the wiki for a given branch.
e.g. number of ready requirements, active requirements, deprecated requirements, having a manual flag, ...

Note: If a requirement has a references list, but no entry for the given branch, it must count as ready.
To consider it as deprecated, a deprecated entry must be added manually.

Describe alternatives you've considered

Adding another requirement phase if entries exist, but not for the given branch.
Might be more confusing than just taking it as ready.
Using another phase would also make it impossible to actually consider it as ready in this case.