@minhpnq1807/contextos 0.5.52 → 0.5.53

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.53
+
+- **Optional adapter positioning:** Clarified that ContextOS core works standalone and that `code-review-graph`, `codegraph`, and `agent-memory` are optional adapters. Skill Router scoring now exposes separate `importGraphScore`, `externalGraphScore`, and `memoryScore` fields so missing adapters degrade to zero score instead of becoming install/runtime requirements.
+- **Adapter-aware benchmark update:** Updated the Skill Router formula to reserve explicit weights for local import graph, optional external graph, and optional memory adapters. The 52-case internal benchmark now reports Top-1 Accuracy 94.2%, Top-3 Recall 94.2%, False Positive Rate 0.0%, Confidence Calibration 100.0%, and Negative Gate Accuracy 100.0%.
+- **Release safety docs:** Added a README safety model covering standalone install, optional adapters, fail-open hooks, local-only telemetry, no hook network calls, and no postinstall behavior.
+- **Launch roadmap template:** Added a GitHub issue template for release hardening, README polish, benchmarks, optional adapters, setup, and telemetry roadmap work.
+
 ## 0.5.52
 
 - **Release candidate polish:** Updated README positioning around ContextOS as a runtime context router, added npm/CI/license badges, a same-prompt/different-repo demo section, a benchmark table, a 30-second install callout, and an AGENTS.md vs RAG vs ContextOS comparison table.

package/README.md

@@ -46,7 +46,7 @@ Skill Router internal fixture benchmark:
 | Metric | Result |
 | --- | ---: |
 | Cases | 52 |
-| Top-1 Accuracy | 92.3% |
+| Top-1 Accuracy | 94.2% |
 | Top-3 Recall | 94.2% |
 | False Positive Rate | 0.0% |
 | Confidence Calibration | 100.0% |
@@ -145,6 +145,21 @@ The problem is not that agents cannot read `AGENTS.md`. The problem is that larg
 | Generic RAG | Semantically related files or snippets. | It usually does not route skills/workflows or prove rule compliance. |
 | ContextOS | Task-routed rules, files, skills, workflows, and evidence. | Requires local setup and warm indexes for best results. |
 
+## Safety Model
+
+ContextOS is designed to be OSS-friendly and low-friction:
+
+| Guarantee | Behavior |
+| --- | --- |
+| Standalone by default | `ctx setup` works without `code-review-graph`, `codegraph`, or `agent-memory`. |
+| Optional adapters | Graph and memory backends add signal when available; missing adapters contribute score `0`. |
+| Fail-open hooks | Prompt hooks return local context or nothing instead of blocking the agent when MCP, embeddings, graph, or memory is unavailable. |
+| Local-only telemetry | Reports, prompt history, evidence, and telemetry stay under `~/.ctx/contextos/`. |
+| No hook network calls | Prompt and stop hooks do not call external services. Install/warm commands may download the local embedding model when explicitly run. |
+| No postinstall surprise | `npm install` only installs the CLI. Setup runs only when you call `ctx setup`. |
+
+Positioning: ContextOS works standalone and gets smarter when graph or memory adapters are available.
+
 ## Quick Commands
 
 | Command | Use it for |
@@ -543,7 +558,17 @@ These files are local telemetry only. Hooks do not make network calls.
 
 ## Project Understanding
 
-ContextOS does not try to replace `code-review-graph`. It uses it as the project-understanding layer when the target repo has already built a graph database.
+ContextOS works standalone. The core path is local rules, file embeddings, import graph expansion, skill routing, workflow routing, and evidence capture.
+
+Project graph and memory backends are optional adapters:
+
+| Adapter | What it adds | Required? |
+| --- | --- | --- |
+| `code-review-graph` | Blast radius, semantic node search, and test relationships. | No |
+| `codegraph` | Symbol/call graph context once its MCP schema is stable. | No |
+| `agent-memory` / `agentmemory` | Prior task history, decisions, and recurring bug-fix context. | No |
+
+ContextOS does not require `code-review-graph`, `codegraph`, or `agent-memory` to install or run. It gets smarter when those backends are available; when they are missing, the adapter scores stay at zero and the hook continues with local context.
 
 For file suggestions, ContextOS now runs a local RAG-style retrieval pass:
 
@@ -553,12 +578,12 @@ prompt
   -> ctx-mcp reads AGENTS.md and scores rules with local MiniLM
   -> query the persisted file-vector index in embeddings.db for semantic file candidates
   -> expand candidates through relative import graph links
-  -> query code-review-graph semantic_search_nodes with seed entity names
-  -> merge and deduplicate semantic, import-graph, and code-review-graph matches
+  -> optionally query code-review-graph semantic_search_nodes with seed entity names
+  -> merge and deduplicate semantic, import-graph, and optional graph matches
   -> inject top suggested files with graph evidence reasons
 ```
 
-This keeps the hook fast and local while still using graph semantics when available. The graph search path is visible in runtime data through file reasons such as `graph:content-moderation.service`.
+This keeps the hook fast and local while still using graph semantics when available. The graph search path is visible in runtime data through file reasons such as `graph:content-moderation.service`. When no graph adapter is available, file suggestions still use local file vectors and import graph expansion.
 
 Prompt scoring does not walk the repository for file candidates or import expansion. `ctx install` and `ctx embeddings warm` rebuild the persisted file-vector index and one-hop import adjacency index by walking source paths once; prompt hooks query those indexes directly. Rules, files, skills, and workflows are scored concurrently with `Promise.all()`.
 
@@ -576,14 +601,18 @@ Skill ranking uses Skill Router v2. ContextOS still starts with semantic retriev
 
 ```text
 final_score =
-  semantic_score * 0.35
+  semantic_score * 0.30
 + prompt_trigger_score * 0.20
-+ project_evidence_score * 0.25
++ project_evidence_score * 0.20
 + file_config_score * 0.10
-+ graph_score * 0.05
++ import_graph_score * 0.10
++ external_graph_score * 0.05
++ memory_score * 0.05
 - negative_penalty * 0.20
 ```
 
+`external_graph_score` is supplied by optional project graph adapters such as `code-review-graph` or `codegraph`. `memory_score` is reserved for optional memory adapters such as `agent-memory`. Without those adapters, both scores are `0`.
+
 Skill metadata can live beside `SKILL.md` as `skill.yaml`:
 
 ```yaml
@@ -625,7 +654,7 @@ Current local benchmark:
 
 ```text
 Cases: 52
-Top-1 Accuracy: 92.3%
+Top-1 Accuracy: 94.2%
 Top-3 Recall: 94.2%
 False Positive Rate: 0.0%
 Confidence Calibration: 100.0%

package/bin/ctx.js

@@ -679,7 +679,7 @@ async function skillsDoctor(task) {
   }
   for (const skill of result.skills) {
     console.log(`${Number(skill.confidence || skill.score || 0).toFixed(2)}  ${skill.confidenceBand || "low"}  ${skill.name}`);
-    console.log(`      semantic:${Number(skill.semanticScore || 0).toFixed(2)} prompt:${Number(skill.promptTriggerScore || 0).toFixed(2)} project:${Number(skill.projectEvidenceScore || 0).toFixed(2)} files:${Number(skill.fileConfigScore || 0).toFixed(2)} negative:${Number(skill.negativePenalty || 0).toFixed(2)}`);
+    console.log(`      semantic:${Number(skill.semanticScore || 0).toFixed(2)} prompt:${Number(skill.promptTriggerScore || 0).toFixed(2)} project:${Number(skill.projectEvidenceScore || 0).toFixed(2)} files:${Number(skill.fileConfigScore || 0).toFixed(2)} import:${Number(skill.importGraphScore || 0).toFixed(2)} graph:${Number(skill.externalGraphScore || skill.graphScore || 0).toFixed(2)} memory:${Number(skill.memoryScore || 0).toFixed(2)} negative:${Number(skill.negativePenalty || 0).toFixed(2)}`);
     if (skill.evidence?.length) console.log(`      evidence: ${skill.evidence.join(", ")}`);
     if (skill.negativeEvidence?.length) console.log(`      rejected signals: ${skill.negativeEvidence.join(", ")}`);
   }

package/eval/skill-routing/cases.yaml

@@ -362,5 +362,5 @@ cases:
   - prompt: react native eas submit failed
     fixture: expo-eas
     expected: [eas, mobile-deployment]
-    allowed: [github-actions-ci-cd]
+    allowed: [github-actions-ci-cd, build-log-debugging]
     rejected: [vercel-deployment]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.52",
+  "version": "0.5.53",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.5.52",
+  "version": "0.5.53",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/skill-discoverer.js

@@ -565,13 +565,17 @@ function hybridSkillScore(skill, { prompt, projectEvidence }) {
   const negativePenalty = Math.max(negativeDependencies.score, negativeFiles.score, negativePrompts.score);
   const projectEvidenceScore = dependencyEvidence.score;
   const fileConfigScore = fileEvidence.score;
-  const graphScore = 0;
+  const importGraphScore = 0;
+  const externalGraphScore = 0;
+  const memoryScore = 0;
   const hybridScore = Math.max(0, Math.min(1,
-    semanticScore * 0.35
+    semanticScore * 0.30
     + promptMatch.score * 0.20
-    + projectEvidenceScore * 0.25
+    + projectEvidenceScore * 0.20
     + fileConfigScore * 0.10
-    + graphScore * 0.05
+    + importGraphScore * 0.10
+    + externalGraphScore * 0.05
+    + memoryScore * 0.05
     - negativePenalty * 0.20
   ));
   const explicit = (skill.reasons || []).includes("explicit-skill");
@@ -609,7 +613,10 @@ function hybridSkillScore(skill, { prompt, projectEvidence }) {
     promptTriggerScore: promptMatch.score,
     projectEvidenceScore,
     fileConfigScore,
-    graphScore,
+    importGraphScore,
+    externalGraphScore,
+    memoryScore,
+    graphScore: externalGraphScore,
     negativePenalty,
     rankScore,
     explicit,
@@ -639,7 +646,7 @@ function calibrateSkillConfidence(score, {
   if (isAmbiguousPrompt(prompt) && !(hasDependencyEvidence && hasFileEvidence) && !explicit) {
     confidence = Math.min(confidence, 0.64);
   }
-  if (hasPromptEvidence && hasProjectEvidence && confidence >= 0.5) {
+  if (hasPromptEvidence && hasProjectEvidence && confidence >= 0.45) {
     confidence = Math.max(confidence, 0.68);
   }
   if (hasDependencyEvidence && hasFileEvidence) {