@grifhinz/logics-manager 2.1.1 → 2.1.2

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.1.2-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)
@@ -167,6 +167,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 +198,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 +402,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.1.2

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
 
 

package/logics_manager/cli.py

@@ -39,67 +39,48 @@ ROOT_COMMANDS = (
 def _build_root_help() -> str:
     sections = [
         "Logics Manager CLI",
-        "Canonical CLI for workflow, validation, and runtime ops.",
+        "Canonical CLI for Logics workflow, validation, MCP, and runtime ops.",
         "",
         "Usage:",
         "  logics-manager <command> [args...]",
-        "  logics-manager config show [options]",
+        "  logics-manager <command> --help",
         "",
         "Top-level options:",
         "  -h, --help      Show this help message and exit.",
-        "  -v, --version   Print the installed version.",
-        "  --version       Print the installed version.",
+        "  -v, --version   Print the installed version and exit.",
         "",
-        "Commands:",
-        "  bootstrap",
-        "    Prepare or check the workflow tree and generated instructions.",
-        "    Options: --check, --format {text,json}",
-        "",
-        "  flow",
-        "    Create and manage workflow docs.",
-        "    Subcommands: new, list, companion, promote, split, close, finish",
-        "    Key flags: --title, --slug, --from-version, --understanding, --confidence, --status, --complexity, --theme, --progress, --format {text,json}, --dry-run",
-        "",
-        "  sync",
-        "    Synchronize workflow transitions and exports.",
-        "    Subcommands: close-eligible-requests, refresh-mermaid-signatures, schema-status, read-doc, list-docs, search-docs, update-indicators, append-note, context-pack, export-graph",
-        "",
-        "  assist",
-        "    Inspect runtime signals and build context bundles.",
-        "    Subcommands: runtime-status, diff-risk, commit-plan, changed-surface-summary, doc-consistency, review-checklist, validation-checklist, validation-summary, test-impact-summary, roi-report, claude-bridges, context, claude-instructions, next-step, request-draft, spec-first-pass, backlog-groom, closure-summary",
-        "",
-        "  audit",
-        "    Audit request, backlog, and task consistency.",
-        "    Options: --stale-days, --skip-ac-traceability, --skip-gates, --legacy-cutoff-version, --format {text,json}, --group-by-doc, --autofix-ac-traceability, --paths, --refs, --since-version, --token-hygiene, --autofix-structure, --governance-profile",
-        "",
-        "  index",
-        "    Generate `logics/INDEX.md` from the workflow corpus.",
-        "    Options: --out, --format {text,json}",
-        "",
-        "  lint",
-        "    Lint workflow documents for filenames, headings, and indicators.",
-        "    Options: --require-status, --format {text,json}",
-        "",
-        "  config show",
-        "    Render the merged runtime config.",
-        "    Options: --format {text,json}",
+        "Common workflows:",
+        '  logics-manager flow new request --title "My request"',
+        "  logics-manager audit --group-by-doc",
+        "  logics-manager sync refresh-mermaid-signatures",
+        "  logics-manager mcp tunnel --repo-root . --port 8765",
         "",
-        "  doctor",
-        "    Check required workflow directories and schema metadata.",
-        "    Options: --format {text,json}",
+        "Workflow authoring:",
+        "  flow       Create, promote, split, close, and finish workflow docs.",
+        "             Subcommands: new, list, companion, promote, split, close, finish",
+        "  sync       Maintain generated workflow state and doc metadata.",
+        "             Subcommands: close-eligible-requests, refresh-mermaid-signatures,",
+        "                          schema-status, read-doc, list-docs, search-docs,",
+        "                          update-indicators, append-note, context-pack, export-graph",
+        "  index      Generate logics/INDEX.md from the workflow corpus.",
         "",
-        "  mcp",
-        "    Expose bounded Logics tools for MCP clients.",
-        "    Subcommands: serve, serve-http, connect, tools, call",
+        "Validation:",
+        "  lint       Check filenames, headings, indicators, and changed-doc hygiene.",
+        "  audit      Check workflow consistency and traceability.",
+        "             Use --governance-profile {relaxed,standard,strict}.",
+        "             JSON output includes issue_count, warning_count, can_continue,",
+        "             and release_ready for agent workflows.",
+        "  doctor     Check required workflow directories and schema metadata.",
         "",
-        "  self-update",
-        "    Update the installed Python or npm package.",
-        "    Options: --manager {auto,pip,npm}, --package, --python-package, --dry-run",
+        "Agent and integration surfaces:",
+        "  assist     Inspect runtime signals and build bounded context bundles.",
+        "  mcp        Expose bounded Logics tools for MCP clients.",
+        "             Subcommands: serve, serve-http, connect, tunnel, tools, call",
+        "  config     Render merged runtime config. Example: config show --format json",
         "",
-        "Examples:",
-        '  logics-manager flow new request --title "My request"',
-        "  logics-manager audit",
-        "  logics-manager config show --format json",
+        "Maintenance:",
+        "  bootstrap  Prepare or check the workflow tree and generated instructions.",
+        "  self-update Update the installed Python or npm package.",
     ]
     return "\n".join(sections)
 

package/logics_manager/lint.py

@@ -578,12 +578,26 @@ def lint_payload(repo_root: Path, *, require_status: bool = False) -> dict[str,
             if warnings:
                 all_warnings.append((rel_path, warnings))
 
+    issues = [{"path": path.as_posix(), "message": issue, "severity": "blocking"} for path, issues in all_issues for issue in issues]
+    warnings: list[dict[str, str]] = []
+    for path, path_warnings in all_warnings:
+        for warning in path_warnings:
+            item = {"path": path.as_posix(), "message": warning, "severity": "warning"}
+            if "Mermaid context signature" in warning:
+                item["repair_command"] = "logics-manager sync refresh-mermaid-signatures"
+            warnings.append(item)
     return {
-        "ok": not all_issues,
-        "issue_count": sum(len(issues) for _path, issues in all_issues),
-        "warning_count": sum(len(warnings) for _path, warnings in all_warnings),
-        "issues": [{"path": path.as_posix(), "message": issue} for path, issues in all_issues for issue in issues],
-        "warnings": [{"path": path.as_posix(), "message": warning} for path, warnings in all_warnings for warning in warnings],
+        "ok": not issues,
+        "can_continue": not issues,
+        "release_ready": not issues and not warnings,
+        "issue_count": len(issues),
+        "warning_count": len(warnings),
+        "strict_count": 0,
+        "finding_count": len(issues) + len(warnings),
+        "issues": issues,
+        "warnings": warnings,
+        "strict": [],
+        "findings": [*issues, *warnings],
     }
 
 
@@ -594,11 +608,11 @@ def render_lint(repo_root: Path, *, require_status: bool = False, output_format:
     if not payload["issues"] and not payload["warnings"]:
         return "Logics lint: OK"
     if not payload["issues"]:
-        lines = ["Logics lint: OK (warnings)"]
+        lines = ["Logics lint: OK (warnings)", f"Blocking issues: {payload['issue_count']}; warnings: {payload['warning_count']}"]
         for warning in payload["warnings"]:
             lines.append(f"- {warning['path']}: WARNING: {warning['message']}")
         return "\n".join(lines)
-    lines = ["Logics lint: FAILED"]
+    lines = ["Logics lint: FAILED", f"Blocking issues: {payload['issue_count']}; warnings: {payload['warning_count']}"]
     for issue in payload["issues"]:
         lines.append(f"- {issue['path']}: {issue['message']}")
     for warning in payload["warnings"]:

package/logics_manager/mcp.py

@@ -8,8 +8,10 @@ import json
 import os
 import re
 import secrets
+import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Any
 from urllib.error import URLError
@@ -115,6 +117,17 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         ),
         "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": False},
     },
+    {
+        "name": "list_companion_docs",
+        "description": "List Logics companion documents such as product briefs and architecture decisions.",
+        "inputSchema": _tool_schema(
+            {
+                "kind": {"type": "string", "enum": ["all", "product", "architecture"]},
+                "limit": {"type": "integer"},
+            }
+        ),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
     {
         "name": "list_active_work",
         "description": "List active Logics request, backlog, and task documents.",
@@ -277,6 +290,25 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         "inputSchema": _tool_schema({"paths": {"type": "array", "items": {"type": "string"}}}),
         "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
     },
+    {
+        "name": "delete_logics_file",
+        "description": "Delete one bounded Logics Markdown file from an approved Logics directory.",
+        "inputSchema": _tool_schema({"path": {"type": "string"}, "dry_run": {"type": "boolean"}}, ["path"]),
+        "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": True},
+    },
+    {
+        "name": "rename_logics_file",
+        "description": "Rename one bounded Logics Markdown file within approved Logics directories.",
+        "inputSchema": _tool_schema(
+            {
+                "source_path": {"type": "string"},
+                "destination_path": {"type": "string"},
+                "dry_run": {"type": "boolean"},
+            },
+            ["source_path", "destination_path"],
+        ),
+        "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": False},
+    },
 ]
 TOOLS_BY_NAME = {str(tool["name"]): tool for tool in TOOL_DEFINITIONS}
 
@@ -354,6 +386,13 @@ def _relative_path(repo_root: Path, raw_path: str, allowed_dirs: tuple[str, ...]
     return normalized
 
 
+def _markdown_file_path(repo_root: Path, raw_path: str, allowed_dirs: tuple[str, ...] = ALLOWED_WRITE_DIRS) -> Path:
+    rel_path = _relative_path(repo_root, raw_path, allowed_dirs)
+    if rel_path.suffix != ".md":
+        raise McpToolError("invalid_path", "Only Markdown files are accepted.", details={"path": raw_path, "extension": rel_path.suffix})
+    return rel_path
+
+
 def _run_command(repo_root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
     command = [sys.executable, "-m", "logics_manager", *args]
     result = subprocess.run(command, cwd=repo_root, check=False, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -511,8 +550,16 @@ def _audit_status(repo_root: Path) -> dict[str, Any]:
     payload = audit_payload(repo_root, legacy_cutoff_version="1.1.0", group_by_doc=True)
     return {
         "ok": bool(payload.get("ok")),
+        "can_continue": bool(payload.get("can_continue", payload.get("ok"))),
+        "release_ready": bool(payload.get("release_ready", payload.get("ok"))),
         "issue_count": payload.get("issue_count", 0),
+        "warning_count": payload.get("warning_count", 0),
+        "strict_count": payload.get("strict_count", 0),
+        "finding_count": payload.get("finding_count", payload.get("issue_count", 0)),
         "issues": payload.get("issues", []),
+        "warnings": payload.get("warnings", []),
+        "strict": payload.get("strict", []),
+        "findings": payload.get("findings", payload.get("issues", [])),
         "issues_by_doc": payload.get("issues_by_doc", {}),
     }
 
@@ -597,6 +644,74 @@ def _document_preview(repo_root: Path, rel_path: str, *, max_chars: int = 1600)
     }
 
 
+def _indicator_from_lines(lines: list[str], key: str) -> str | None:
+    prefix = f"> {key}:"
+    for line in lines:
+        if line.startswith(prefix):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def _title_from_heading(lines: list[str], fallback: str) -> str:
+    for line in lines:
+        if not line.startswith("## "):
+            continue
+        heading = line[3:].strip()
+        if " - " in heading:
+            return heading.split(" - ", 1)[1].strip()
+        return heading
+    return fallback
+
+
+def _parse_companion_refs(value: str | None) -> list[str]:
+    if not value or value == "(none yet)":
+        return []
+    refs = re.findall(r"`([^`]+)`", value)
+    if refs:
+        return [ref for ref in refs if ref not in {"(none)", "(none yet)"}]
+    return [part.strip() for part in value.split(",") if part.strip() and part.strip() not in {"(none)", "(none yet)"}]
+
+
+def _companion_doc_entry(repo_root: Path, rel_path: Path, kind: str) -> dict[str, Any]:
+    path = repo_root / rel_path
+    lines = path.read_text(encoding="utf-8").splitlines()
+    related = {
+        "request": _parse_companion_refs(_indicator_from_lines(lines, "Related request")),
+        "backlog": _parse_companion_refs(_indicator_from_lines(lines, "Related backlog")),
+        "task": _parse_companion_refs(_indicator_from_lines(lines, "Related task")),
+        "architecture": _parse_companion_refs(_indicator_from_lines(lines, "Related architecture")),
+    }
+    return {
+        "kind": kind,
+        "ref": rel_path.stem,
+        "path": rel_path.as_posix(),
+        "title": _title_from_heading(lines, rel_path.stem),
+        "status": _indicator_from_lines(lines, "Status") or "Unknown",
+        "related": {key: refs for key, refs in related.items() if refs},
+    }
+
+
+def _list_companion_docs(repo_root: Path, *, kind: str = "all", limit: int = 50) -> dict[str, Any]:
+    if kind not in {"all", "product", "architecture"}:
+        raise McpToolError("invalid_argument_value", "Unsupported companion document kind.", details={"kind": kind, "allowed": ["all", "product", "architecture"]})
+    targets = []
+    if kind in {"all", "product"}:
+        targets.append(("product", Path("logics/product"), "prod_*.md"))
+    if kind in {"all", "architecture"}:
+        targets.append(("architecture", Path("logics/architecture"), "adr_*.md"))
+    items: list[dict[str, Any]] = []
+    for doc_kind, directory, pattern in targets:
+        root = repo_root / directory
+        if not root.is_dir():
+            continue
+        for path in sorted(root.glob(pattern)):
+            if path.is_file() and not path.is_symlink():
+                items.append(_companion_doc_entry(repo_root, path.relative_to(repo_root), doc_kind))
+    items.sort(key=lambda item: str(item["path"]))
+    bounded_items = items[:limit]
+    return {"kind": kind, "limit": limit, "count": len(bounded_items), "total_count": len(items), "items": bounded_items}
+
+
 def _bounded_int(value: Any, *, default: int, maximum: int) -> int:
     if not isinstance(value, int) or isinstance(value, bool):
         return default
@@ -659,6 +774,9 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         if kind not in {"all", "request", "backlog", "task"}:
             raise McpToolError("invalid_argument_value", "Unsupported list kind.", details={"kind": kind, "allowed": ["all", "request", "backlog", "task"]})
         return {"ok": True, "items": flow_list_payload(root, kind=kind)["entries"]}
+    if name == "list_companion_docs":
+        payload = _list_companion_docs(root, kind=str(args.get("kind") or "all"), limit=_bounded_int(args.get("limit"), default=50, maximum=200))
+        return {"ok": True, **payload}
     if name == "read_logics_doc":
         try:
             payload = read_logics_doc_payload(root, str(args.get("source") or ""), max_chars=_bounded_int(args.get("max_chars"), default=4000, maximum=12000), sections=args.get("sections") if isinstance(args.get("sections"), list) else None)
@@ -813,6 +931,58 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         raw_paths = args.get("paths")
         paths = [str(path) for path in raw_paths] if isinstance(raw_paths, list) else None
         return _show_git_diff(root, paths)
+    if name == "delete_logics_file":
+        rel_path = _markdown_file_path(root, str(args.get("path") or ""))
+        target = root / rel_path
+        dry_run = bool(args.get("dry_run", False))
+        if not target.exists():
+            raise McpToolError("not_found", "Logics file not found.", details={"path": rel_path.as_posix()})
+        if not target.is_file() or target.is_symlink():
+            raise McpToolError("invalid_path", "Only regular Markdown files can be deleted.", details={"path": rel_path.as_posix()})
+        if not dry_run:
+            _ensure_no_dirty_conflict(root, [rel_path.as_posix()])
+            target.unlink()
+        return _workflow_write_result(
+            root,
+            {
+                "path": rel_path.as_posix(),
+                "dry_run": dry_run,
+                "deleted": not dry_run,
+                "would_delete": dry_run,
+                "summary": f"{'Would delete' if dry_run else 'Deleted'} {rel_path.as_posix()}",
+            },
+            paths=[rel_path.as_posix()],
+        )
+    if name == "rename_logics_file":
+        source_rel = _markdown_file_path(root, str(args.get("source_path") or ""))
+        destination_rel = _markdown_file_path(root, str(args.get("destination_path") or ""))
+        source = root / source_rel
+        destination = root / destination_rel
+        dry_run = bool(args.get("dry_run", False))
+        if source_rel == destination_rel:
+            raise McpToolError("invalid_path", "Source and destination paths must differ.", details={"source_path": source_rel.as_posix(), "destination_path": destination_rel.as_posix()})
+        if not source.exists():
+            raise McpToolError("not_found", "Source Logics file not found.", details={"source_path": source_rel.as_posix()})
+        if not source.is_file() or source.is_symlink():
+            raise McpToolError("invalid_path", "Only regular Markdown files can be renamed.", details={"source_path": source_rel.as_posix()})
+        if destination.exists():
+            raise McpToolError("already_exists", "Destination already exists.", details={"destination_path": destination_rel.as_posix()})
+        if not dry_run:
+            _ensure_no_dirty_conflict(root, [source_rel.as_posix(), destination_rel.as_posix()])
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            source.rename(destination)
+        return _workflow_write_result(
+            root,
+            {
+                "source_path": source_rel.as_posix(),
+                "destination_path": destination_rel.as_posix(),
+                "dry_run": dry_run,
+                "renamed": not dry_run,
+                "would_rename": dry_run,
+                "summary": f"{'Would rename' if dry_run else 'Renamed'} {source_rel.as_posix()} to {destination_rel.as_posix()}",
+            },
+            paths=[source_rel.as_posix(), destination_rel.as_posix()],
+        )
 
     if name == "create_request":
         title = str(args.get("title") or "").strip()
@@ -969,11 +1139,48 @@ def make_http_handler(repo_root: Path, *, bearer_token: str | None = None) -> ty
             self.end_headers()
             self.wfile.write(encoded)
 
+        def _authorized(self) -> bool:
+            if not bearer_token:
+                return True
+            expected = f"Bearer {bearer_token}"
+            actual = self.headers.get("Authorization", "")
+            if secrets.compare_digest(actual, expected):
+                return True
+            self.send_response(401)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("WWW-Authenticate", 'Bearer realm="logics-mcp"')
+            encoded = json.dumps({"ok": False, "error": "unauthorized", "message": "Missing or invalid bearer token."}, separators=(",", ":")).encode("utf-8")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+            return False
+
+        def _send_sse_stream(self) -> None:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "keep-alive")
+            self.end_headers()
+            self.wfile.write(b": logics-manager-mcp ready\n\n")
+            self.wfile.flush()
+            while True:
+                time.sleep(15)
+                self.wfile.write(b": keepalive\n\n")
+                self.wfile.flush()
+
         def do_GET(self) -> None:
             parsed = urlparse(self.path)
             if parsed.path == "/health":
                 self._send_json(200, {"ok": True, "server": "logics-manager-mcp", "version": _server_version()})
                 return
+            if parsed.path == "/mcp":
+                if not self._authorized():
+                    return
+                try:
+                    self._send_sse_stream()
+                except (BrokenPipeError, ConnectionResetError):
+                    return
+                return
             self._send_json(404, {"ok": False, "error": "not_found", "message": "Use POST /mcp for JSON-RPC."})
 
         def do_POST(self) -> None:
@@ -981,18 +1188,8 @@ def make_http_handler(repo_root: Path, *, bearer_token: str | None = None) -> ty
             if parsed.path != "/mcp":
                 self._send_json(404, {"ok": False, "error": "not_found", "message": "Use POST /mcp for JSON-RPC."})
                 return
-            if bearer_token:
-                expected = f"Bearer {bearer_token}"
-                actual = self.headers.get("Authorization", "")
-                if not secrets.compare_digest(actual, expected):
-                    self.send_response(401)
-                    self.send_header("Content-Type", "application/json")
-                    self.send_header("WWW-Authenticate", 'Bearer realm="logics-mcp"')
-                    encoded = json.dumps({"ok": False, "error": "unauthorized", "message": "Missing or invalid bearer token."}, separators=(",", ":")).encode("utf-8")
-                    self.send_header("Content-Length", str(len(encoded)))
-                    self.end_headers()
-                    self.wfile.write(encoded)
-                    return
+            if not self._authorized():
+                return
             try:
                 length = int(self.headers.get("Content-Length", "0"))
             except ValueError:
@@ -1051,17 +1248,29 @@ def _connector_urls(public_url: str | None) -> dict[str, str]:
     return {"public_url": base, "mcp_url": mcp_url, "health_url": health_url}
 
 
-def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str | None = None, public_url: str | None = None) -> dict[str, Any]:
-    token = bearer_token or secrets.token_urlsafe(32)
+def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str | None = None, public_url: str | None = None, no_bearer: bool = False, project_binary: str | None = None) -> dict[str, Any]:
+    token = None if no_bearer else bearer_token or secrets.token_urlsafe(32)
     urls = _connector_urls(public_url)
     local_mcp_url = f"http://{host}:{port}/mcp"
     local_health_url = f"http://{host}:{port}/health"
-    server_command = f'{AUTH_ENV_VAR}="{token}" python3 -m logics_manager mcp serve-http --repo-root {repo_root.as_posix()} --host {host} --port {port}'
+    launcher = project_binary or "python3 -m logics_manager"
+    auth_args = "" if no_bearer else f'{AUTH_ENV_VAR}="{token}" '
+    server_command = f"{auth_args}{launcher} mcp serve-http --repo-root {repo_root.as_posix()} --host {host} --port {port}"
+    auth_header = None if no_bearer else f"Authorization: Bearer {token}"
+    cleanup = [
+        "Stop the HTTPS tunnel process.",
+        "Stop the local mcp serve-http process with Ctrl-C.",
+    ]
+    if token:
+        cleanup.append("Treat the bearer token as expired once the local session is stopped.")
+    else:
+        cleanup.append("Treat the public tunnel URL as exposed until both processes are stopped.")
     return {
         "ok": True,
         "repo_root": repo_root.as_posix(),
         "bearer_token": token,
-        "auth_header": f"Authorization: Bearer {token}",
+        "auth_mode": "none" if no_bearer else "bearer",
+        "auth_header": auth_header,
         "local_mcp_url": local_mcp_url,
         "local_health_url": local_health_url,
         "server_command": server_command,
@@ -1069,23 +1278,20 @@ def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str |
         "chatgpt": {
             "developer_mode": True,
             "mcp_url": urls.get("mcp_url", "<your HTTPS tunnel URL>/mcp"),
-            "auth_type": "Bearer token",
+            "auth_type": "None" if no_bearer else "Bearer token",
             "auth_value": token,
         },
         "smoke_checks": {
             "health": urls.get("health_url", f"<your HTTPS tunnel URL>/health"),
             "mcp_tools_list": urls.get("mcp_url", "<your HTTPS tunnel URL>/mcp"),
         },
-        "cleanup": [
-            "Stop the HTTPS tunnel process.",
-            "Stop the local mcp serve-http process with Ctrl-C.",
-            "Treat the bearer token as expired once the local session is stopped.",
-        ],
+        "warnings": ["No-bearer mode is unauthenticated. Use only for short-lived local debugging."] if no_bearer else [],
+        "cleanup": cleanup,
         **urls,
     }
 
 
-def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float = 5.0) -> dict[str, Any]:
+def connector_smoke_check(public_url: str, bearer_token: str | None = None, *, timeout: float = 5.0) -> dict[str, Any]:
     urls = _connector_urls(public_url)
     health_ok = False
     mcp_ok = False
@@ -1097,7 +1303,10 @@ def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float
         errors.append(f"health: {exc}")
     try:
         body = json.dumps({"jsonrpc": JSONRPC_VERSION, "id": 1, "method": "tools/list", "params": {}}).encode("utf-8")
-        request = Request(urls["mcp_url"], data=body, headers={"Content-Type": "application/json", "Authorization": f"Bearer {bearer_token}"}, method="POST")
+        headers = {"Content-Type": "application/json"}
+        if bearer_token:
+            headers["Authorization"] = f"Bearer {bearer_token}"
+        request = Request(urls["mcp_url"], data=body, headers=headers, method="POST")
         with urlopen(request, timeout=timeout) as response:
             payload = json.loads(response.read().decode("utf-8"))
             mcp_ok = response.status == 200 and "result" in payload
@@ -1108,10 +1317,13 @@ def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float
 
 def _print_connector_plan(plan: dict[str, Any]) -> None:
     print("Logics MCP Connector")
+    for warning in plan.get("warnings", []):
+        print(f"WARNING: {warning}")
     print(f"Server command:\n  {plan['server_command']}")
     print(f"Tunnel target: {plan['tunnel_target']}")
     print(f"ChatGPT developer-mode MCP URL: {plan['chatgpt']['mcp_url']}")
-    print(f"Authorization header: {plan['auth_header']}")
+    print(f"Auth mode: {plan['auth_mode']}")
+    print(f"Authorization header: {plan['auth_header'] or '(none)'}")
     print("Smoke checks:")
     print(f"  health: {plan['smoke_checks']['health']}")
     print(f"  mcp tools/list: {plan['smoke_checks']['mcp_tools_list']}")
@@ -1120,6 +1332,88 @@ def _print_connector_plan(plan: dict[str, Any]) -> None:
         print(f"  - {item}")
 
 
+def _project_binary_path(repo_root: Path) -> str:
+    candidate = repo_root / "scripts" / "npm" / "logics-manager.mjs"
+    if candidate.is_file():
+        return f"node {candidate.as_posix()}"
+    return "python3 -m logics_manager"
+
+
+def _terminate_process(process: subprocess.Popen[str]) -> None:
+    if process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+
+
+def launch_tunnel(
+    *,
+    repo_root: Path,
+    host: str,
+    port: int,
+    bearer_token: str | None = None,
+    no_bearer: bool = False,
+    tunnel_command: list[str] | None = None,
+) -> int:
+    token = None if no_bearer else bearer_token or secrets.token_urlsafe(32)
+    server_command = [sys.executable, "-m", "logics_manager", "mcp", "serve-http", "--repo-root", repo_root.as_posix(), "--host", host, "--port", str(port)]
+    env = os.environ.copy()
+    if token:
+        env[AUTH_ENV_VAR] = token
+    tunnel_command = tunnel_command or ["npx", "localtunnel", "--port", str(port)]
+    server = subprocess.Popen(server_command, cwd=repo_root, env=env, text=True)
+    tunnel: subprocess.Popen[str] | None = None
+    previous_sigint = signal.getsignal(signal.SIGINT)
+    previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+    def stop(_signum: int | None = None, _frame: Any | None = None) -> None:
+        if tunnel is not None:
+            _terminate_process(tunnel)
+        _terminate_process(server)
+
+    signal.signal(signal.SIGINT, stop)
+    signal.signal(signal.SIGTERM, stop)
+    try:
+        time.sleep(0.8)
+        if server.poll() is not None:
+            return server.returncode or 1
+        tunnel = subprocess.Popen(tunnel_command, cwd=repo_root, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        public_url = None
+        start = time.monotonic()
+        while time.monotonic() - start < 30:
+            if tunnel.poll() is not None:
+                return tunnel.returncode or 1
+            line = tunnel.stdout.readline() if tunnel.stdout else ""
+            if not line:
+                time.sleep(0.1)
+                continue
+            print(line.rstrip())
+            match = re.search(r"https://\S+", line)
+            if match:
+                public_url = match.group(0).rstrip("/")
+                break
+        if not public_url:
+            raise McpToolError("command_failed", "Tunnel command did not print a public HTTPS URL within 30 seconds.", details={"command": tunnel_command})
+        plan = connector_plan(repo_root=repo_root, host=host, port=port, bearer_token=token, public_url=public_url, no_bearer=no_bearer, project_binary=_project_binary_path(repo_root))
+        _print_connector_plan(plan)
+        print("Processes are running. Press Ctrl-C to stop server and tunnel.")
+        while True:
+            if server.poll() is not None:
+                return server.returncode or 1
+            if tunnel.poll() is not None:
+                return tunnel.returncode or 1
+            time.sleep(1)
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        stop()
+        signal.signal(signal.SIGINT, previous_sigint)
+        signal.signal(signal.SIGTERM, previous_sigterm)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="logics-manager mcp", description="Run or inspect the Logics MCP server.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -1141,9 +1435,16 @@ def main(argv: list[str] | None = None) -> int:
     connect.add_argument("--host", default="127.0.0.1")
     connect.add_argument("--port", type=int, default=8765)
     connect.add_argument("--bearer-token", default=None)
+    connect.add_argument("--no-bearer", action="store_true", help="Print a no-auth connector plan for short-lived local debugging.")
     connect.add_argument("--public-url", default=None, help="Optional HTTPS tunnel URL used for copyable ChatGPT setup and smoke checks.")
     connect.add_argument("--check", action="store_true", help="Run /health and authenticated /mcp smoke checks against --public-url.")
     connect.add_argument("--format", choices=("text", "json"), default="text")
+    tunnel = sub.add_parser("tunnel", help="Start the local MCP HTTP server plus an HTTPS localtunnel session.")
+    tunnel.add_argument("--repo-root", default=None)
+    tunnel.add_argument("--host", default="127.0.0.1")
+    tunnel.add_argument("--port", type=int, default=8765)
+    tunnel.add_argument("--bearer-token", default=None)
+    tunnel.add_argument("--no-bearer", action="store_true", help="Run without bearer auth for short-lived local debugging.")
     parsed = parser.parse_args(argv)
 
     if parsed.command == "tools":
@@ -1170,11 +1471,13 @@ def main(argv: list[str] | None = None) -> int:
         return 0
     if parsed.command == "connect":
         root = _repo_root(Path(parsed.repo_root) if parsed.repo_root else None)
-        plan = connector_plan(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, public_url=parsed.public_url)
+        if parsed.no_bearer and parsed.bearer_token:
+            raise SystemExit("--no-bearer cannot be combined with --bearer-token.")
+        plan = connector_plan(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, public_url=parsed.public_url, no_bearer=parsed.no_bearer, project_binary=_project_binary_path(root))
         if parsed.check:
             if not parsed.public_url:
                 raise SystemExit("--check requires --public-url.")
-            plan["check"] = connector_smoke_check(parsed.public_url, str(plan["bearer_token"]))
+            plan["check"] = connector_smoke_check(parsed.public_url, str(plan["bearer_token"]) if plan["bearer_token"] else None)
             plan["ok"] = bool(plan["check"]["ok"])
         if parsed.format == "json":
             print(json.dumps(plan, indent=2, sort_keys=True))
@@ -1185,4 +1488,9 @@ def main(argv: list[str] | None = None) -> int:
                 for error in plan["check"]["errors"]:
                     print(f"  - {error}")
         return 0 if plan["ok"] else 1
+    if parsed.command == "tunnel":
+        if parsed.no_bearer and parsed.bearer_token:
+            raise SystemExit("--no-bearer cannot be combined with --bearer-token.")
+        root = _repo_root(Path(parsed.repo_root) if parsed.repo_root else None)
+        return launch_tunnel(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, no_bearer=parsed.no_bearer)
     return 1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@grifhinz/logics-manager",
   "displayName": "Logics Orchestrator",
   "description": "Visual orchestration for Logics workflows inside VS Code.",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "publisher": "cdx-logics",
   "icon": "media/icon.png",
   "repository": {
@@ -130,6 +130,7 @@
     "lint:es": "eslint src/**/*.ts",
     "lint:logics": "node scripts/run-python.mjs -m logics_manager lint",
     "audit:logics": "node scripts/run-python.mjs -m logics_manager audit && node scripts/run-python.mjs -m logics_manager lint",
+    "audit:logics:strict": "node scripts/run-python.mjs -m logics_manager audit --governance-profile strict && node scripts/run-python.mjs -m logics_manager lint --require-status",
     "audit:ci": "node scripts/check-npm-audit.mjs",
     "logics:finish:task": "node scripts/run-python.mjs -m logics_manager flow finish task",
     "ci:fast": "npm run compile && npm run lint && npm run test:coverage && npm run test:smoke && npm run lint:logics && npm run package:ci",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logics-manager"
-version = "2.1.1"
+version = "2.1.2"
 description = "Canonical Logics CLI"
 requires-python = ">=3.10"
 

package/scripts/npm/logics-manager.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -91,6 +92,17 @@ export function runLogicsManager(argv = process.argv.slice(2), platform = proces
   return 1;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+export function isDirectInvocation(importUrl = import.meta.url, argvPath = process.argv[1]) {
+  if (!argvPath) {
+    return false;
+  }
+  try {
+    return importUrl === pathToFileURL(realpathSync(argvPath)).href;
+  } catch {
+    return importUrl === pathToFileURL(argvPath).href;
+  }
+}
+
+if (isDirectInvocation()) {
   process.exit(runLogicsManager());
 }