@grifhinz/logics-manager 2.1.1 → 2.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.1.1-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.2.0-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -101,12 +101,55 @@ Useful commands:
 
 ```bash
 logics-manager flow list
-logics-manager flow promote request-to-backlog logics/request/req_001_example.md
-logics-manager flow promote backlog-to-task logics/backlog/item_001_example.md
-logics-manager flow finish task logics/tasks/task_001_example.md
+logics-manager flow promote request-to-backlog req_001_example
+logics-manager flow promote backlog-to-task item_001_example
+logics-manager flow finish task task_001_example
 logics-manager sync context-pack req_001_example --format json
 ```
 
+### CLI Contracts
+
+Workflow target arguments accept these forms:
+
+- a workflow ref, such as `req_001_example`, `item_001_example`, or `task_001_example`;
+- a repo-relative Markdown path under the matching Logics directory, such as `logics/request/req_001_example.md`;
+- an absolute path only when it resolves inside the current repository.
+
+Mutation commands reject `..` traversal and files outside the repository before writing. Output paths passed with `--out` must also be repo-relative and remain inside the repository after resolution. Configured log/cache paths in `logics.yaml` may be repo-relative or absolute, but absolute paths must still resolve inside the current repository.
+
+When a command supports `--format json`, stdout is a machine-readable JSON payload. Human-oriented status, diagnostics, and progress text should not be mixed into stdout for JSON mode. This makes JSON-mode commands safe to pipe into tools such as `jq` or consume from scripts.
+
+`--json` is a shorthand for `--format json` on commands that support JSON output.
+
+JSON-capable operator commands:
+
+| Command | Purpose | JSON output |
+| --- | --- | --- |
+| `logics-manager status` | Summarize open workflow docs and next actions. | `--format json` or `--json` |
+| `logics-manager health` | Show workflow health counts and issue signals. | `--format json` or `--json` |
+| `logics-manager followups` | List follow-up areas with request creation commands. | `--format json` or `--json` |
+| `logics-manager product-consistency` | Check product brief lineage links. | `--format json` or `--json` |
+| `logics-manager search <query>` | Search workflow docs directly. | `--format json` or `--json` |
+| `logics-manager index` | Regenerate `logics/INDEX.md`. | `--format json` or `--json` |
+| `logics-manager lint` | Validate doc shape and changed-doc hygiene. | `--format json` or `--json` |
+| `logics-manager audit` | Validate workflow traceability and governance. | `--format json` or `--json` |
+| `logics-manager sync ...` | Read, list, search, repair, and export workflow state. | `--format json` or `--json` on supported subcommands |
+| `logics-manager assist ...` | Build review, validation, context, and runtime summaries. | `--format json` or `--json` on supported subcommands |
+| `logics-manager flow ...` | Create, promote, split, close, finish, and list docs. | `--format json` or `--json` on supported subcommands |
+
+Operator triage flow:
+
+```bash
+logics-manager status --json
+logics-manager health --json
+logics-manager product-consistency --json
+logics-manager followups --source-kind product --json
+```
+
+Use `status` first when you need the next work signal. Use `health` for corpus-level anomalies. Use `product-consistency --strict` in release checks when active product briefs must have valid lineage. Use `followups` for open actionable follow-up areas; add `--include-closed` only when auditing historical docs.
+
+Multi-file workflow mutations such as `flow promote`, `flow split`, and `flow finish` validate their direct inputs before writing. New workflow docs are created with exclusive filesystem writes, so an ID collision fails instead of overwriting an existing file; rerun the command to allocate a fresh ID after reviewing `git status`/`git diff`. They still operate on Markdown files in the working tree rather than through a database or transaction service; if the filesystem fails mid-write, recover with git status/diff and rerun after cleanup.
+
 To update the installed CLI later:
 
 ```bash
@@ -167,6 +210,25 @@ LOGICS_MCP_BEARER_TOKEN="$(openssl rand -hex 32)" python3 -m logics_manager mcp
 
 `POST /mcp` accepts `Authorization: Bearer <token>` when `LOGICS_MCP_BEARER_TOKEN` or `--bearer-token` is set. Keep `/health` unauthenticated for smoke checks, but do not expose `/mcp` publicly without a bearer token.
 
+Start the local server and a temporary `localtunnel` session in one command:
+
+```bash
+python3 -m logics_manager mcp tunnel --repo-root . --port 8765
+```
+
+For short-lived live debugging only, run without bearer auth:
+
+```bash
+python3 -m logics_manager mcp tunnel --repo-root . --port 8765 --no-bearer
+```
+
+During project development, the same commands can be run through the repository binary:
+
+```bash
+node scripts/npm/logics-manager.mjs mcp tunnel --repo-root . --port 8765
+node scripts/npm/logics-manager.mjs mcp tunnel --repo-root . --port 8765 --no-bearer
+```
+
 Generate a local connector plan:
 
 ```bash
@@ -179,7 +241,13 @@ With an HTTPS tunnel URL:
 python3 -m logics_manager mcp connect --repo-root . --public-url https://example-tunnel.example --check
 ```
 
-The connector plan prints the bearer token, server command, tunnel target, assistant connector URL, auth header, smoke checks, and cleanup steps.
+For a no-bearer plan:
+
+```bash
+python3 -m logics_manager mcp connect --repo-root . --public-url https://example-tunnel.example --no-bearer --check
+```
+
+The connector plan prints the bearer token when used, server command, tunnel target, assistant connector URL, auth mode, auth header, smoke checks, warnings, and cleanup steps.
 
 ## Assistant Model
 
@@ -377,10 +445,17 @@ If the current plugin version is already published, `logics-manager assist next-
 - VSIX package validation: `npm run package:ci`
 - Logics docs lint: `npm run lint:logics`
 - Logics workflow audit + docs lint: `npm run audit:logics`
+- Strict Logics governance audit: `npm run audit:logics:strict`
 - Fast extension-focused local check: `npm run ci:fast`
 - Full CI-equivalent local check: `npm run ci:check`
 - Security audit policy gate: `npm run audit:ci`
 
+`npm run audit:logics` uses the default active-work profile. It blocks correctness and traceability failures, but reports early companion-doc polish such as missing overview Mermaid diagrams as warnings so drafting and agent handoffs can continue.
+
+`npm run audit:logics:strict` uses the strict governance profile. Use it before release or governance review when companion docs must be complete and warning-class findings should be resolved.
+
+`logics-manager audit --format json` and `logics-manager lint --format json` expose `issue_count`, `warning_count`, `strict_count`, `finding_count`, `can_continue`, and `release_ready`. Agents should treat `issue_count > 0` as blocking active work, and `release_ready: false` as a signal that cleanup remains before release-grade validation.
+
 `npm run ci:check` mirrors the blocking repository CI contract, including Logics strict-status lint, request auto-close sync verification, workflow audit, Python tests, CLI smoke checks, TypeScript validation, extension tests, and VSIX packaging.
 
 `npm run audit:ci` enforces the repository audit policy locally. It blocks new actionable vulnerabilities and only allows the explicitly documented temporary exceptions tracked in the backlog.

package/VERSION

@@ -1 +1 @@
-2.1.1
+2.2.0

package/logics_manager/assist.py

@@ -14,6 +14,7 @@ from typing import Any
 from .config import ConfigError, find_repo_root, load_repo_config
 from .doctor import doctor_payload
 from .lint import lint_payload
+from .path_utils import resolve_repo_config_path, resolve_repo_output_path
 from .termstyle import colorize_help
 
 
@@ -88,8 +89,9 @@ def _hybrid_measurement_log(config: dict[str, object]) -> str:
     return str(_get_nested(config, "hybrid_assist", "measurement_log", default=DEFAULT_HYBRID_MEASUREMENT_LOG))
 
 
-def _repo_path(repo_root: Path, value: str | None, default: str) -> Path:
-    return (repo_root / (value or default)).resolve()
+def _repo_path(repo_root: Path, value: str | None, default: str, *, label: str) -> Path:
+    resolved, _relative = resolve_repo_config_path(repo_root, value or default, label=label)
+    return resolved
 
 
 def _parse_package_version(repo_root: Path) -> str:
@@ -641,6 +643,35 @@ def _git_changed_paths(repo_root: Path) -> list[str]:
     return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
 
 
+def _git_lines(repo_root: Path, args: list[str]) -> list[str]:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=repo_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if completed.returncode != 0:
+        return []
+    return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
+
+
+def _git_range_changed_paths(repo_root: Path, since: str) -> list[str]:
+    return sorted(set(_git_lines(repo_root, ["diff", "--name-only", "--relative=.", f"{since}..HEAD"])))
+
+
+def _git_range_commits(repo_root: Path, since: str) -> list[dict[str, str]]:
+    commits: list[dict[str, str]] = []
+    for line in _git_lines(repo_root, ["log", "--oneline", f"{since}..HEAD"]):
+        commit, _, subject = line.partition(" ")
+        commits.append({"commit": commit, "subject": subject})
+    return commits
+
+
 def _is_low_risk_generated_path(path: str) -> bool:
     normalized = path.strip().replace("\\", "/")
     filename = normalized.rsplit("/", 1)[-1]
@@ -1346,6 +1377,12 @@ def build_parser() -> argparse.ArgumentParser:
     closure_summary.add_argument("--dry-run", action="store_true")
     closure_summary.set_defaults(func=cmd_closure_summary)
 
+    handoff = sub.add_parser("handoff", help="Summarize commits, changed surfaces, Logics docs, validations, and next actions.")
+    handoff.add_argument("--since", required=True)
+    handoff.add_argument("--format", choices=("text", "json"), default="text")
+    handoff.add_argument("--dry-run", action="store_true")
+    handoff.set_defaults(func=cmd_handoff)
+
     return parser
 
 
@@ -1417,11 +1454,15 @@ def _build_help() -> str:
             "  closure-summary [ref]",
             "    Summarize a delivered request, backlog item, or task.",
             "    Flags: --format {text,json}, --dry-run",
+            "  handoff",
+            "    Summarize commits, changed surfaces, Logics docs, validations, and next actions.",
+            "    Flags: --since, --format {text,json}, --dry-run",
             "",
             "Examples:",
             "  logics-manager assist runtime-status --format json",
             "  logics-manager assist context request req_001_my_request --profile deep",
             "  logics-manager assist request-draft --intent \"Improve onboarding\"",
+            "  logics-manager assist handoff --since HEAD~1",
         ]
     )
 
@@ -1527,6 +1568,21 @@ def _build_command_help(command: str) -> str:
                 "  --dry-run",
             ]
         )
+    if command == "handoff":
+        return "\n".join(
+            [
+                "Logics Assist Handoff",
+                "Summarize commits, changed surfaces, Logics docs, validations, and next actions.",
+                "",
+                "Usage:",
+                "  logics-manager assist handoff --since <rev> [args...]",
+                "",
+                "Flags:",
+                "  --since",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
     if command == "roi-report":
         return "\n".join(
             [
@@ -2023,6 +2079,77 @@ def _build_closure_summary(repo_root: Path, ref: str | None) -> dict[str, object
     }
 
 
+def _doc_title_from_path(path: Path) -> str:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return path.stem
+    for line in lines:
+        if line.startswith("## "):
+            payload = line.removeprefix("## ").strip()
+            if " - " in payload:
+                return payload.split(" - ", 1)[1].strip()
+            return payload
+    return path.stem
+
+
+def _validation_lines_from_task(path: Path) -> list[str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    values: list[str] = []
+    for line in _section_lines(lines, "Validation"):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        value = stripped[2:].strip()
+        if value and not value.lower().startswith("run `") and not value.lower().startswith("run the "):
+            values.append(value)
+    return values
+
+
+def _build_handoff(repo_root: Path, since: str) -> dict[str, object]:
+    changed_paths = _git_range_changed_paths(repo_root, since)
+    commits = _git_range_commits(repo_root, since)
+    surface = _build_changed_surface_summary(changed_paths)
+    logics_docs: list[dict[str, object]] = []
+    validations: list[str] = []
+    for rel_path in changed_paths:
+        if not rel_path.startswith("logics/") or not rel_path.endswith(".md"):
+            continue
+        path = repo_root / rel_path
+        kind = path.parent.name
+        entry = {
+            "path": rel_path,
+            "ref": path.stem,
+            "kind": kind,
+            "title": _doc_title_from_path(path),
+            "status": _doc_status(path) if path.is_file() else "Unknown",
+        }
+        logics_docs.append(entry)
+        if kind == "tasks":
+            validations.extend(_validation_lines_from_task(path))
+    next_actions = [
+        "Run lint/audit if not already included in validation evidence.",
+        "Review changed files before committing or handing off.",
+    ]
+    if any(path.startswith("logics_manager/") for path in changed_paths):
+        next_actions.append("Run `PYTHONPATH=\"$PWD\" pytest python_tests -q` for Python CLI changes.")
+    if any(path.startswith("src/") for path in changed_paths):
+        next_actions.append("Run the TypeScript/vitest checks for extension changes.")
+    return {
+        "since": since,
+        "commit_count": len(commits),
+        "commits": commits,
+        "changed_paths": changed_paths,
+        "surface": surface,
+        "logics_docs": logics_docs,
+        "validations": sorted(set(validations)),
+        "next_actions": next_actions,
+    }
+
+
 def _build_context_pack(repo_root: Path, seed_ref: str, *, mode: str, profile: str) -> dict[str, object]:
     docs = _workflow_docs(repo_root)
     selected: list[Path] = []
@@ -2236,8 +2363,8 @@ def cmd_test_impact_summary(args: argparse.Namespace) -> dict[str, object]:
 def cmd_roi_report(args: argparse.Namespace) -> dict[str, object]:
     repo_root = find_repo_root(Path.cwd())
     config, config_path = load_repo_config(repo_root)
-    audit_log = _repo_path(repo_root, args.audit_log, _hybrid_audit_log(config))
-    measurement_log = _repo_path(repo_root, args.measurement_log, _hybrid_measurement_log(config))
+    audit_log = _repo_path(repo_root, args.audit_log, _hybrid_audit_log(config), label="configured audit_log")
+    measurement_log = _repo_path(repo_root, args.measurement_log, _hybrid_measurement_log(config), label="configured measurement_log")
     payload = _build_hybrid_roi_report(
         repo_root,
         audit_log=audit_log,
@@ -2251,13 +2378,16 @@ def cmd_roi_report(args: argparse.Namespace) -> dict[str, object]:
     payload["config_path"] = str(config_path.relative_to(repo_root)) if config_path is not None else None
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2307,13 +2437,16 @@ def cmd_runtime_status(args: argparse.Namespace) -> dict[str, object]:
     }
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2363,14 +2496,14 @@ def cmd_request_draft(args: argparse.Namespace) -> dict[str, object]:
         **_build_request_draft(repo_root, intent=args.intent),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2409,14 +2542,14 @@ def cmd_spec_first_pass(args: argparse.Namespace) -> dict[str, object]:
         **_build_spec_first_pass(repo_root, args.ref),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2455,16 +2588,16 @@ def cmd_backlog_groom(args: argparse.Namespace) -> dict[str, object]:
         **_build_backlog_groom(repo_root, args.ref),
     }
     if args.execution_mode == "execute":
-        out_path = repo_root / payload["path"]
+        out_path, output_path = resolve_repo_output_path(repo_root, str(payload["path"]), label="output")
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(payload["content"], encoding="utf-8")
             payload["written"] = True
-            request_path = repo_root / payload["request_path"]
+            request_path, _request_output_path = resolve_repo_output_path(repo_root, str(payload["request_path"]), label="request_path")
             _append_section_bullets(request_path, "Backlog", [f"`{payload['ref']}`"], dry_run=False)
         else:
             payload["written"] = False
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        payload["output_path"] = output_path
     else:
         payload["written"] = False
     if args.format == "json":
@@ -2513,6 +2646,34 @@ def cmd_closure_summary(args: argparse.Namespace) -> dict[str, object]:
     return payload
 
 
+def cmd_handoff(args: argparse.Namespace) -> dict[str, object]:
+    repo_root = find_repo_root(Path.cwd())
+    config, config_path = load_repo_config(repo_root)
+    payload = {
+        "command": "assist",
+        "kind": "handoff",
+        "repo_root": repo_root.as_posix(),
+        "config_path": str(config_path.relative_to(repo_root)) if config_path is not None else None,
+        **_build_handoff(repo_root, args.since),
+    }
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"Handoff since {payload['since']}:")
+        print(f"- commits: {payload['commit_count']}")
+        print(f"- changed paths: {len(payload['changed_paths'])}")
+        print(f"- primary surface: {payload['surface']['primary_category']}")
+        for commit in payload["commits"][:8]:
+            print(f"- commit: {commit['commit']} {commit['subject']}")
+        for doc in payload["logics_docs"][:8]:
+            print(f"- logics: {doc['ref']} [{doc['status']}] {doc['path']}")
+        for validation in payload["validations"][:8]:
+            print(f"- validation: {validation}")
+        for action in payload["next_actions"]:
+            print(f"- next: {action}")
+    return payload
+
+
 def cmd_context(args: argparse.Namespace) -> dict[str, object]:
     repo_root = find_repo_root(Path.cwd())
     config, config_path = load_repo_config(repo_root)
@@ -2554,13 +2715,16 @@ def cmd_context(args: argparse.Namespace) -> dict[str, object]:
     }
 
     if args.out:
-        out_path = (repo_root / args.out).resolve()
+        out_path, output_path = resolve_repo_output_path(repo_root, args.out)
+        payload["output_path"] = output_path
         serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
         if not args.dry_run:
             out_path.parent.mkdir(parents=True, exist_ok=True)
             out_path.write_text(serialized, encoding="utf-8")
-        print(f"Wrote {out_path.relative_to(repo_root)}")
-        payload["output_path"] = out_path.relative_to(repo_root).as_posix()
+        if args.format == "json":
+            print(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            print(f"Wrote {output_path}")
     elif args.format == "json":
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
@@ -2576,7 +2740,7 @@ def main(argv: list[str]) -> int:
     if not argv or argv[0] in HELP_FLAGS:
         _print_help(_build_help())
         return 0
-    if argv[0] in {"runtime-status", "context", "request-draft", "spec-first-pass", "backlog-groom", "closure-summary", "roi-report", "diff-risk", "commit-plan", "changed-surface-summary", "doc-consistency", "review-checklist", "validation-checklist", "validation-summary", "test-impact-summary", "claude-bridges", "claude-instructions", "next-step"} and len(argv) > 1 and argv[1] in HELP_FLAGS:
+    if argv[0] in {"runtime-status", "context", "request-draft", "spec-first-pass", "backlog-groom", "closure-summary", "handoff", "roi-report", "diff-risk", "commit-plan", "changed-surface-summary", "doc-consistency", "review-checklist", "validation-checklist", "validation-summary", "test-impact-summary", "claude-bridges", "claude-instructions", "next-step"} and len(argv) > 1 and argv[1] in HELP_FLAGS:
         _print_help(_build_command_help(argv[0]))
         return 0
     parser = build_parser()

package/logics_manager/audit.py

@@ -107,6 +107,8 @@ class AuditIssue:
     code: str
     path: Path | None
     message: str
+    severity: str = "blocking"
+    repair_command: str | None = None
 
 
 def _indicator_value(lines: list[str], key: str) -> str | None:
@@ -167,6 +169,15 @@ def _has_mermaid_block(text: str) -> bool:
     return "```mermaid" in text
 
 
+def _companion_doc_is_mature(doc: "DocMeta") -> bool:
+    status = _status_normalized(doc.status)
+    if doc.kind.kind == "product":
+        return status in {"active", "validated", "archived"}
+    if doc.kind.kind == "architecture":
+        return status in {"accepted", "superseded", "archived"}
+    return False
+
+
 def _decision_framing_value(text: str, label: str) -> str | None:
     pattern = re.compile(rf"^\s*-\s*{re.escape(label)}\s*:\s*(.+)\s*$", re.MULTILINE)
     match = pattern.search(text)
@@ -511,11 +522,11 @@ def _rel(repo_root: Path, path: Path | None) -> str:
 
 
 def _sorted_issues(issues: Iterable[AuditIssue], repo_root: Path) -> list[AuditIssue]:
-    unique: dict[tuple[str, str, str], AuditIssue] = {}
+    unique: dict[tuple[str, str, str, str], AuditIssue] = {}
     for issue in issues:
-        key = (_rel(repo_root, issue.path), issue.code, issue.message)
+        key = (issue.severity, _rel(repo_root, issue.path), issue.code, issue.message)
         unique.setdefault(key, issue)
-    return sorted(unique.values(), key=lambda issue: (_rel(repo_root, issue.path), issue.code, issue.message))
+    return sorted(unique.values(), key=lambda issue: (_rel(repo_root, issue.path), issue.severity, issue.code, issue.message))
 
 
 def _scan_hybrid_cache_for_credentials(repo_root: Path) -> list[AuditIssue]:
@@ -584,6 +595,7 @@ def audit_payload(
     docs = _apply_scope(all_docs, repo_root, paths or [], refs or [], scope_since)
 
     issues: list[AuditIssue] = []
+    strict_governance = governance_profile == "strict"
     autofix_targets: dict[Path, set[str]] = {}
     autofix_modified: list[Path] = []
 
@@ -652,20 +664,26 @@ def audit_payload(
         for prefix in ("req", "item", "task", "prod", "adr"):
             linked_refs.update(_extract_refs(doc.text, prefix))
 
+        companion_is_mature = _companion_doc_is_mature(doc)
+
         if not any(ref.startswith(("req_", "item_", "task_")) for ref in linked_refs):
+            primary_link_severity = "blocking" if strict_governance or companion_is_mature else "warning"
             issues.append(
                 AuditIssue(
                     code="companion_doc_missing_primary_link",
                     path=doc.path,
                     message="companion doc has no linked request, backlog item, or task reference",
+                    severity=primary_link_severity,
                 )
             )
         if not _has_mermaid_block(doc.text):
+            mermaid_severity = "blocking" if strict_governance or companion_is_mature else "warning"
             issues.append(
                 AuditIssue(
                     code="companion_doc_missing_mermaid",
                     path=doc.path,
                     message="companion doc is missing its overview Mermaid diagram",
+                    severity=mermaid_severity,
                 )
             )
         placeholders = COMPANION_PLACEHOLDERS.get(doc.kind.kind, ())
@@ -850,20 +868,46 @@ def audit_payload(
 
     by_code: dict[str, int] = {}
     by_path: dict[str, int] = {}
-    serialized: list[dict[str, str]] = []
+    by_severity: dict[str, int] = {}
+    serialized_findings: list[dict[str, str]] = []
     for issue in sorted_issues:
         rel_path = _rel(repo_root, issue.path)
         by_code[issue.code] = by_code.get(issue.code, 0) + 1
         by_path[rel_path] = by_path.get(rel_path, 0) + 1
-        serialized.append({"code": issue.code, "path": rel_path, "message": issue.message})
+        by_severity[issue.severity] = by_severity.get(issue.severity, 0) + 1
+        finding = {"code": issue.code, "path": rel_path, "message": issue.message, "severity": issue.severity}
+        if issue.repair_command:
+            finding["repair_command"] = issue.repair_command
+        serialized_findings.append(finding)
+
+    blocking_findings = [finding for finding in serialized_findings if finding["severity"] == "blocking"]
+    warning_findings = [finding for finding in serialized_findings if finding["severity"] == "warning"]
+    strict_findings = [finding for finding in serialized_findings if finding["severity"] == "strict"]
+    findings_by_doc: dict[str, list[dict[str, str]]] = {}
+    for finding in serialized_findings:
+        findings_by_doc.setdefault(finding["path"], []).append(finding)
+    issues_by_doc: dict[str, list[dict[str, str]]] = {}
+    for finding in blocking_findings:
+        issues_by_doc.setdefault(finding["path"], []).append(finding)
 
     return {
-        "ok": not sorted_issues,
-        "issue_count": len(sorted_issues),
-        "issues": serialized,
+        "ok": not blocking_findings,
+        "can_continue": not blocking_findings,
+        "release_ready": not blocking_findings and not warning_findings and not strict_findings,
+        "issue_count": len(blocking_findings),
+        "warning_count": len(warning_findings),
+        "strict_count": len(strict_findings),
+        "finding_count": len(serialized_findings),
+        "issues": blocking_findings,
+        "warnings": warning_findings,
+        "strict": strict_findings,
+        "findings": serialized_findings,
+        "issues_by_doc": dict(sorted(issues_by_doc.items())),
+        "findings_by_doc": dict(sorted(findings_by_doc.items())),
         "counts": {
             "by_code": dict(sorted(by_code.items())),
             "by_path": dict(sorted(by_path.items())),
+            "by_severity": dict(sorted(by_severity.items())),
         },
         "autofix": {
             "enabled": autofix_ac_traceability or autofix_structure,
@@ -909,25 +953,35 @@ def render_audit(
     if output_format == "json":
         return json.dumps(payload, indent=2, sort_keys=True)
 
-    lines = ["Workflow audit: OK" if payload["ok"] else "Workflow audit: FAILED", f"Workflow docs inspected: {payload['workflow_doc_count']}"]
-    issues = payload["issues"]
-    if not issues:
+    if payload["ok"] and (payload["warning_count"] or payload["strict_count"]):
+        status_line = "Workflow audit: OK (warnings)"
+    else:
+        status_line = "Workflow audit: OK" if payload["ok"] else "Workflow audit: FAILED"
+    lines = [
+        status_line,
+        f"Workflow docs inspected: {payload['workflow_doc_count']}",
+        f"Blocking issues: {payload['issue_count']}; warnings: {payload['warning_count']}; strict-only findings: {payload['strict_count']}",
+    ]
+    findings = payload["findings"]
+    if not findings:
         return "\n".join(lines)
     if not group_by_doc:
-        for issue in issues:
+        for issue in findings:
+            prefix = "WARNING" if issue["severity"] == "warning" else "STRICT" if issue["severity"] == "strict" else "BLOCKING"
             if issue["path"] == "(global)":
-                lines.append(f"- [{issue['code']}] {issue['message']}")
+                lines.append(f"- {prefix}: [{issue['code']}] {issue['message']}")
             else:
-                lines.append(f"- {issue['path']}: [{issue['code']}] {issue['message']}")
+                lines.append(f"- {issue['path']}: {prefix}: [{issue['code']}] {issue['message']}")
         return "\n".join(lines)
 
     grouped: dict[str, list[dict[str, str]]] = {}
-    for issue in issues:
+    for issue in findings:
         grouped.setdefault(issue["path"], []).append(issue)
     for rel_path in sorted(grouped):
         lines.append(f"- {rel_path}")
-        for issue in sorted(grouped[rel_path], key=lambda item: (item["code"], item["message"])):
-            lines.append(f"  - [{issue['code']}] {issue['message']}")
+        for issue in sorted(grouped[rel_path], key=lambda item: (item["severity"], item["code"], item["message"])):
+            prefix = "WARNING" if issue["severity"] == "warning" else "STRICT" if issue["severity"] == "strict" else "BLOCKING"
+            lines.append(f"  - {prefix}: [{issue['code']}] {issue['message']}")
     return "\n".join(lines)
 
 
@@ -948,7 +1002,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--since-version", help="Limit the audit to docs with `From version` >= this semantic version.")
     parser.add_argument("--token-hygiene", action="store_true", help="Enable compact AI context and verbosity checks for workflow docs.")
     parser.add_argument("--autofix-structure", action="store_true", help="Deterministically repair missing schema metadata, AI Context, and missing gate sections.")
-    parser.add_argument("--governance-profile", choices=tuple(GOVERNANCE_PROFILES), default="standard", help="Apply a named governance profile when resolving default audit strictness.")
+    parser.add_argument("--governance-profile", choices=tuple(GOVERNANCE_PROFILES), default="standard", help="Apply a named governance profile; `standard` reports early companion-doc polish as warnings, `strict` promotes governance warnings to blockers.")
     return parser