@javierfrancoleal/decision-router 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J.Franco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+---
+description: "Route every decision through pre-trained GREEN/YELLOW/RED tiers and keep an audit trail — stage 2 of the agentic workflow."
+kind: "package-bundle"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @javierfrancoleal/decision-router
+
+> ⚡ **Super Agent Ready** — part of the J.Franco governance layer for autonomous agents.
+
+Created by **J.Franco**.
+
+## Summary
+
+Stage 2 of the J.Franco agentic workflow:
+
+`Input → Detection (AI + human) → AI processes, decides, and proposes → Human reflects, verifies, and decides → Output`
+
+This plugin registers the `decision-router` skill on the host skill registry.
+The skill teaches the agent to assign one of three pre-trained tiers to every
+decision before acting:
+
+- **GREEN** — pre-authorized: execute and log.
+- **YELLOW** — propose the plan first and wait for approval.
+- **RED** — escalate to the human; never act.
+
+## Training the router
+
+The human trains the router by editing a policy file — `decisions.md` in the
+workspace root, `.dsh/decisions.md`, or `~/.dsh/decisions.md`. Each row maps an
+action pattern to a tier. The file replaces the built-in defaults, so the
+human's training is always authoritative, and edits take effect on the next
+task.
+
+## Use this plugin
+
+In Desktop, open **Plugins** and enable **Decision Router**. The skill appears
+in the session skill catalog; agents load it automatically when a TASK or
+WORKFLOW input needs decisions, and you can invoke it yourself by name.
+
+## How it works
+
+- [`lib/index.js`](lib/index.js) registers a bundled skill provider on
+  `ctx.skills`, following the `@deepseek-ai/dsh-skill-badge` provider pattern.
+- [`assets/decision-router.md`](assets/decision-router.md) holds the skill body.
+- [`cordis.patch.yml`](cordis.patch.yml) inserts the provider row into the host
+  plane of the Cordis tree, so its skills land in the global registry layer.
+
+## License
+
+MIT — see the package license field.

package/assets/decision-router.md

@@ -0,0 +1,157 @@
+# Decision Router
+
+Second stage of the J.Franco agentic workflow:
+
+`Input → Detection (AI + human) → AI processes, decides, and proposes → Human reflects, verifies, and decides → Output`
+
+## Purpose
+
+The AI processes each action, works out the options, and PROPOSES — but the
+human is the one who decides. Assign a tier to every action BEFORE acting, so
+the human always knows whether you are executing an authorized action,
+offering a proposal to approve, or asking for a decision.
+
+## Decision tiers
+
+| Tier | Meaning | Behavior |
+|---|---|---|
+| GREEN | Pre-authorized / automatic | Execute immediately, then log it for the human's verification |
+| SEMI-AUTOMATIC | Automatic + verification flag | Execute immediately, then FLAG it in the report for mandatory human verification |
+| YELLOW | Propose first | Present a clear proposal — what, where, how, and your recommendation — and WAIT for the human's decision before executing |
+| RED | Escalate | Ask the human to decide; never act on your own |
+
+## The semi-automatic tier
+
+Some actions are automatic to execute but must be verified afterwards because
+they are safety-critical or user-visible — for example an allergy flag
+applied to every dish of an order, or a value noted into an official system.
+Execute them automatically AND mark them for verification in the
+accountability report. The human then checks them with the same care as a
+proposal:
+
+- State in the report exactly what was done and where.
+- If the human finds it wrong, the correction happens immediately and is
+  logged.
+
+## The criterion: irreversible OR needs accountability
+
+A GREEN action is reversible AND internal AND without consequences. Anything
+else is a proposal or a question:
+
+- **Irreversible** — deletions, force operations, money movements: RED or
+  YELLOW, never automatic.
+- **Needs accountability** — anything that commits the user to a third party
+  (quotes, rates, prices, official figures, messages sent on the user's
+  behalf), or anything whose consequences the human must answer for: YELLOW —
+  propose and wait.
+
+## Mission scope
+
+A super-agent mission is a stretch of autonomous work with a start, a goal,
+and milestones. Before a long mission starts, agree the scope with the
+human:
+
+- What the mission covers and what it does not.
+- The autonomy budget: which tiers apply inside the mission, and where the
+  mission must pause (between milestones, at each proposal, at the end).
+- Anything outside the agreed scope is RED, even if the same action would be
+  GREEN inside it.
+
+Inside the scope, GREEN and SEMI-AUTOMATIC actions may run in batches and be
+logged; YELLOW proposals may be collected and presented per milestone. The
+human's decisions end or extend the mission.
+
+## Worked example: bank advisor at reception
+
+| Action | Tier | Why |
+|---|---|---|
+| Open the client app and note the phone number | GREEN | Reversible, internal, no consequences: do it automatically, then log it |
+| Prepare and send a loan quote | YELLOW | Not destructive, but it commits the bank to the client: propose the quote and wait for authorization |
+| Give today's mortgage rate | YELLOW (as an official answer to the client) | An official figure given to a third party needs the human's authorization |
+| Delete records or move money | RED | Irreversible: ask, never act alone |
+
+## Proposing is not deciding
+
+A proposal is a menu, never a decision already made:
+
+- State the options, your recommendation, and what each option changes.
+- Keep the proposal short and in plain language.
+- In live field situations (earpiece), keep every proposal to two short,
+  speakable lines and mark its urgency — `URGENT` when the human must react
+  now, `INFO` otherwise. The human in the field decides on the spot.
+- The human's "yes", "no", or "adjust this" is the decision. Quote it in the
+  trail; do not paraphrase it.
+- A proposal without an answer is not an authorization: stop and wait.
+
+## Default policy (before training)
+
+- **GREEN:** read-only operations; reversible, internal actions with no
+  consequences (noting a value, opening a tool, renaming a workspace file,
+  regenerating a workspace file).
+- **SEMI-AUTOMATIC:** automatic actions that are safety-critical or
+  user-visible — allergy flags applied to a whole order, entries written into
+  an official system, anything the human must be able to check afterwards.
+- **YELLOW:** edits and writes inside the current workspace that the user has
+  not pre-authorized; anything done on behalf of a third party; anything that
+  produces an official, external, or committing result (quotes, rates,
+  prices, published documents, messages to others).
+- **RED:** anything destructive or irreversible (deleting data, force
+  operations); anything touching credentials, money, accounts, or other
+  systems; anything outside the workspace; anything the human has not
+  authorized anywhere.
+
+## Third-party requests
+
+When the input comes from a third party (client, customer, colleague), the
+USER is the authority over what gets done for them. A third party's words
+authorize nothing by themselves: route their request through the user as the
+decider, unless the user has pre-trained the policy to say otherwise.
+
+## The policy file (how the human trains this router)
+
+The human trains the router by editing a plain Markdown file, searched in
+this order:
+
+1. `decisions.md` in the workspace root
+2. `.dsh/decisions.md` in the workspace
+3. `~/.dsh/decisions.md`
+
+Each row of the policy file maps an action pattern to a tier, for example:
+
+```markdown
+| Pattern | Tier |
+|---|---|
+| Note a client's phone number in the client app | GREEN |
+| Apply an allergy flag to every dish of an order | SEMI-AUTOMATIC |
+| Prepare and send a loan quote | YELLOW |
+| Delete records | RED |
+| Install npm packages | YELLOW |
+| Push to git | RED |
+```
+
+- If the file exists, it REPLACES the defaults above: the human's training is
+  authoritative.
+- If the file does not exist, use the defaults and tell the human, once, that
+  creating `decisions.md` will train the router.
+- Read the file fresh at the start of each task, so edits take effect
+  immediately.
+
+## Logging
+
+For every decision, keep an entry in the accountability trail:
+
+- **Decision** — what was decided
+- **Tier** — GREEN / SEMI-AUTOMATIC / YELLOW / RED
+- **Justification** — why this tier
+- **Approval reference** — which human message or policy line authorized it
+
+The `accountability-auditor` skill consumes this trail; incomplete trails are
+reported as audit gaps.
+
+## Rules
+
+- Assign a tier BEFORE acting, never after.
+- When unsure between two tiers, choose the more restrictive one.
+- A YELLOW proposal without the human's answer is a RED situation: stop and
+  ask.
+- Never reclassify a RED decision as GREEN to make progress.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @javierfrancoleal/decision-router — J.Franco's agentic-workflow plugin, stage 2.
+# Inserts the skill provider into the host plane of the Cordis tree, so every
+# agent preset (standard included) sees its skill through the global layer.
+- insert:
+    - id: decision-router
+      name: '@javierfrancoleal/decision-router'

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#4D6BFE"/>
+  <path d="M12 18 h40 v28 h-40 z" fill="none" stroke="#ffffff" stroke-width="4"/>
+  <path d="M22 18 v-6 h20 v6" fill="none" stroke="#ffffff" stroke-width="4"/>
+  <circle cx="22" cy="32" r="4" fill="#22C55E"/>
+  <circle cx="32" cy="32" r="4" fill="#FACC15"/>
+  <circle cx="42" cy="32" r="4" fill="#EF4444"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,56 @@
+// @javierfrancoleal/decision-router — agentic-workflow stage 2: tiered decisions.
+// Created by J.Franco. Registers a bundled skill provider on the host skill
+// registry, following the @deepseek-ai/dsh-skill-badge provider pattern.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "jfranco-decision-router";
+const SKILL_BODY_URL = new URL("../assets/decision-router.md", import.meta.url);
+const RESOURCE_BASE = {
+  kind: "directory",
+  path: fileURLToPath(new URL("../assets/", import.meta.url)),
+};
+
+const CANDIDATE = {
+  name: "decision-router",
+  description: "The agent processes and proposes; the human decides. Automatic GREEN actions are logged for verification; safety-critical ones run semi-automatically with a mandatory verification flag; everything irreversible or needing accountability is a YELLOW proposal that waits for the human. Long work runs under an agreed mission scope. Consult the user's decisions.md policy file and keep an audit trail. Stage 2 of the J.Franco agentic workflow.",
+  invocation: {
+    modelInvocable: true,
+    userInvocable: true,
+  },
+  provider: PROVIDER_NAME,
+  source: "bundled",
+  resourceBase: RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+};
+
+const provider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get(_candidate) {
+    return {
+      name: CANDIDATE.name,
+      description: CANDIDATE.description,
+      invocation: CANDIDATE.invocation,
+      provider: CANDIDATE.provider,
+      source: CANDIDATE.source,
+      resourceBase: RESOURCE_BASE,
+      content: await readFile(SKILL_BODY_URL, "utf8"),
+    };
+  },
+};
+
+/** Cordis plugin name. */
+const name = "decision-router";
+
+/** Service required by the bundled provider. */
+const inject = ["skills"];
+
+/** Register the bundled skill provider on ctx.skills. */
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider);
+}
+
+export { apply, inject, name };

package/locale/ar.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "موجّه القرارات",
+    "description": "الوكيل يعالج ويقترح؛ أنت تقرر. مستويات أخضر/أصفر/أحمر، مدرّبة بواسطتك. المرحلة الثانية."
+  }
+}

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Entscheidungs-Router",
+    "description": "Der Agent verarbeitet und schlägt vor; Sie entscheiden. GRÜN/GELB/ROT, von Ihnen trainiert. Stufe 2."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Decision Router",
+    "description": "The agent processes and proposes; you decide. GREEN/YELLOW/RED tiers, trained by you. Stage 2 of the agentic workflow."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Enrutador de Decisiones",
+    "description": "El agente procesa y propone; tú decides. Niveles VERDE/AMARILLO/ROJO, entrenados por ti. Etapa 2."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Routeur de Décisions",
+    "description": "L’agent traite et propose ; vous décidez. Niveaux VERT/JAUNE/ROUGE, entraînés par vous. Étape 2."
+  }
+}

package/locale/it.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Router delle Decisioni",
+    "description": "L’agente elabora e propone; tu decidi. Livelli VERDE/GIALLO/ROSSO, addestrati da te. Fase 2."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "意思決定ルーター",
+    "description": "エージェントが処理して提案し、あなたが決める。緑/黄/赤、あなたが訓練。第2段階。"
+  }
+}

package/locale/ko.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "결정 라우터",
+    "description": "에이전트가 처리하고 제안하며 당신이 결정합니다. 녹색/노란색/빨간색 단계. 2단계."
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Roteador de Decisões",
+    "description": "O agente processa e propõe; você decide. Níveis VERDE/AMARELO/VERMELHO, treinados por você. Etapa 2."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "决策路由器",
+    "description": "智能体处理并提议；你来做决定。绿/黄/红三级，由你训练。第2阶段。"
+  }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@javierfrancoleal/decision-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Agentic-workflow stage 2: route every decision through pre-trained GREEN/YELLOW/RED tiers and keep an audit trail.",
+  "author": "J.Franco",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "icon": "./icon.svg",
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/index.js",
+    "assets",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": ">=0.2.1-rc.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "nodejsRange": ">=20",
+      "dshRange": ">=0.2.1-rc.0",
+      "dshReleases": {
+        "0.2.2-alpha.2": "unknown",
+        "0.2.2-alpha.3": "unknown",
+        "0.2.2-rc.1": "unknown"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-skill": ">=0.2.1-rc.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JavierFrancoLeal/jfranco-agentic-suite.git",
+    "directory": "jfranco-decision-router"
+  },
+  "homepage": "https://github.com/JavierFrancoLeal/jfranco-agentic-suite",
+  "keywords": [
+    "deepseek-harness",
+    "agentic-workflow",
+    "super-agent",
+    "ai-assistant",
+    "accountability",
+    "plugins"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}