Add problems-solutions library and critical chain

Author: Your Name

README.adoc

@@ -787,3 +787,7 @@ Special thanks to the Elixir, Rust, and ReScript communities for excellent tooli
 **Status:** v1.0.0 Released | **Next:** v1.1 Production Hardening (Q1 2026)
 
 For the latest updates, see link:ROADMAP.adoc[ROADMAP.adoc] and link:STATE.scm[STATE.scm].
+
+== Problems → Solutions
+
+See link:problems-solutions/README.adoc[problems-solutions] for real-world failure cases and how OPSM should resolve them.

ROADMAP.adoc

@@ -13,6 +13,31 @@ toc::[]
 
 == Overview
 
+== Critical Chain (Priority Path)
+
+OPSM’s highest‑impact milestone path is:
+
+1. **Package‑managerless languages** (hardest‑to‑install first)
+2. **Rogue repos / extrepos** (GitHub/GitLab/Bitbucket that lack manifests)
+3. **OS‑package fallback** (when apt/dnf/pacman/rpm‑ostree fail)
+
+This path is additive and does not replace the rest of the roadmap.
+
+=== Example (Smart Install)
+
+[source,bash]
+----
+opsm install [rpm-ostree: gnat ada ats2 v forth factor ldc zig idris2 ghc]   [toolbox: janus arrow paxos kraft raft swi-prolog datalog logtalk qml ocaml j lisp lfe rust gcc gcc-c++]
+----
+
+Expected behavior:
+
+* Classify packages by backend
+* Offer substitutes (e.g., gforth when "forth" missing)
+* Dry‑run plan with conflicts and policy warnings
+* Reversible apply if approved
+
+
 OPSM's roadmap progresses through four major phases:
 
 [source]
@@ -1076,3 +1101,5 @@ Transform OPSM from "8-language package manager" to "universal, intelligent pack
 OPSM becomes a global, federated, verifiable substrate for software distribution across
 languages, platforms, and domains — with strict policy controls, user sovereignty, and
 provable integrity as the default.
+
+

problems-solutions/2026-01-26-rogue-repo-install.adoc

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= Rogue Git repo install (no manifest)
+
+== Context
+
+* Source: GitHub/GitLab/Bitbucket repository
+* No package manager metadata or manifest
+
+== Exact Error
+
+"No package/manifest found" or install fails after clone.
+
+== Expected OPSM Behavior
+
+* Identify project type via heuristics (language, build files)
+* Propose install plan (build + install) with **dry‑run**
+* Use `bitfuckit`/extrepo helpers where applicable
+* Cache build artifacts and report reproducibility hints
+
+== Fallback Strategy
+
+* If no build system, provide interactive build steps
+* If incompatible architecture, offer alternatives or skip
+

problems-solutions/2026-01-26-rpm-ostree-multi-install.adoc

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= rpm-ostree multi‑install with mixed availability
+
+== Context
+
+* OS: Fedora Silverblue
+* Manager: rpm-ostree
+* User wants: batch install with mixed language tooling
+
+== Exact Error
+
+User supplied a mixed list including packages not in rpm‑ostree or only available
+via toolbox/flatpak/source.
+
+== Expected OPSM Behavior
+
+* Parse list and classify per backend.
+* Warn about unresolvable items on rpm‑ostree.
+* Offer alternatives (toolbox, container, source build).
+* Provide **dry‑run** plan before apply.
+
+== Fallback Strategy
+
+* rpm‑ostree for base packages
+* toolbox/distrobox for dev toolchains
+* source/rogue‑repo install for orphaned packages
+
+== Notes
+
+OPSM should auto‑detect architecture constraints (e.g., mac‑only packages) and
+mark as incompatible with explicit reasons.
+

problems-solutions/2026-01-26-unmaintained-compromised.adoc

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= Unmaintained or compromised package
+
+== Context
+
+* Package exists but is unmaintained or flagged
+* User expects normal install
+
+== Expected OPSM Behavior
+
+* Warn clearly in WYSIWYG mode
+* Block in WYSIWYGM unless policy allows
+* Suggest known alternatives
+* Record the decision for audit
+
+== Notes
+
+Signals can come from advisories, maintainer activity, and trust services.
+

problems-solutions/README.adoc

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= Problems → Solutions Library
+:toc: preamble
+:toclevels: 2
+
+This folder collects real‑world package manager failures and how OPSM should
+address them. Add scenarios from your own experience (or from public issue
+threads) with error messages, context, and expected behavior.
+
+== How to Add a Scenario
+
+Create a new file named like:
+
+`YYYY-MM-DD-short-title.adoc`
+
+Include:
+
+* **Context** (OS, distro, package manager)
+* **Exact error**
+* **Expected OPSM behavior**
+* **Fallback strategy**
+* **Notes** (known issues, unmaintained, compromised, etc.)
+
+== Why This Exists
+
+Many package managers fail in recurring ways. OPSM will map these to known
+causes and recommended resolutions, with user‑friendly warnings.
+