@javierfrancoleal/autonomy-grader 0.0.0-stage → 1.1.0

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,45 @@
-# Temporary Holding Version
+---
+description: "Governance layer: grades the reliability of automatic decisions and proposes tier moves — the human approves every change."
+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/autonomy-grader
+
+> ⚡ **Super Agent Ready** — part of the J.Franco governance layer for autonomous agents.
+
+Created by **J.Franco**.
+
+## Summary
+
+The governance layer of the J.Franco agentic workflow. As the AI executes
+more automatic actions, the supervision log accumulates evidence. The
+autonomy-grader turns that evidence into trust:
+
+- grades every action pattern **A / B / C / D** (samples, verifications,
+  corrections, errors);
+- proposes tier moves: reliable patterns toward GREEN, unreliable ones back
+  to YELLOW or RED;
+- computes an overall **autonomy level 1–5** for the domain;
+- proposes the exact `decisions.md` line for every move — and **never
+  changes the rules itself**: the human approves every change.
+
+## Use this plugin
+
+In Desktop, open **Plugins** and enable **Autonomy Grader**. Then, after a
+week of real work, ask "grade" or use `/grade`: the agent reads
+`supervision.md`, grades every pattern, and hands you the Autonomy Report
+with the exact lines to add to `decisions.md`.
+
+## How it works
+
+- [`lib/index.js`](lib/index.js) registers the `autonomy-grader` skill
+  provider on `ctx.skills` and, when the host command registry resolves, the
+  `/grade` command.
+- [`assets/autonomy-grader.md`](assets/autonomy-grader.md) holds the grading
+  protocol.
+- [`cordis.patch.yml`](cordis.patch.yml) inserts the provider row into the
+  host plane of the Cordis tree.
+
+## License
+
+MIT — see the package license field.

package/assets/autonomy-grader.md

@@ -0,0 +1,172 @@
+# Autonomy Grader
+
+The governance layer of the J.Franco agentic workflow: it measures how much
+the AI can be trusted with automatic decisions, and proposes how to adjust
+the tiers. The human approves every change — the grader never changes the
+rules itself.
+
+`Input → Detection (AI + human) → AI processes, decides, and proposes → Human reflects, verifies, and decides → Output`
+
+## Evolution (variation + selection)
+
+The grader is the fitness function; add the variation:
+
+- When a tier has been stable for a while, propose 1-2 CANDIDATE rule
+  mutations (small changes to decisions.md) as YELLOW proposals.
+- Let the next cycle's grades score the candidates; keep winners, discard
+  the rest — with the owner's approval, as always.
+- Never mutate more than one rule at a time: evolution is incremental.
+
+## Purpose
+
+Over time, the supervision log accumulates evidence: which GREEN and
+SEMI-AUTOMATIC actions ran clean, which ones the human corrected, and which
+ones failed. The grader turns that evidence into trust grades and proposes
+tier moves:
+
+- reliable patterns → candidates to move from YELLOW to GREEN (more
+  autonomy);
+- unreliable patterns → candidates to move back to YELLOW or RED (more
+  control).
+
+## When to run
+
+- The human asks: "grade", "how autonomous is it?", `/grade`, or invokes
+  this skill.
+- After a review session over the supervision log.
+- Before expanding a pilot to more positions.
+
+## Data source
+
+Read the supervision trail in this order:
+
+1. `supervision.md` in the workspace root
+2. `.dsh/supervision.md` in the workspace
+3. `~/.dsh/supervision.md`
+4. the current session's accountability reports, if no file exists
+
+If no data exists, say so and stop: the grader never invents evidence.
+
+## Procedure
+
+1. **Collect.** Read every entry: inputs, decisions with tiers, automatic
+   actions, verifications, corrections, and gaps.
+2. **Group.** Group the evidence by action pattern (for example "note a
+   client's phone number", "send an order to the kitchen") — and, when the
+   log records them, also by channel (voice, chat, camera), by mission, and
+   by worker (worker tags come from the panel or the session identity).
+3. **Count per pattern:** samples (executions), verified OK, corrected by the
+   human, and errors or gaps found.
+4. **Score** the pattern:
+
+   - **A** — at least 10 samples, ≥ 95% verified OK, no errors.
+   - **B** — at least 5 samples, ≥ 85% verified OK, no serious errors.
+   - **C** — fewer samples, or 70–85% OK, or minor corrections.
+   - **D** — below 70% OK, or any serious error (wrong data, wrong place,
+     missed safety flag).
+
+5. **Suggest a tier move** for each pattern:
+
+   - **A** → propose moving the pattern to GREEN (or keeping it GREEN),
+     quoting the exact `decisions.md` line.
+   - **B** → keep as is; keep watching.
+   - **C** → keep YELLOW (or return to YELLOW); more samples needed.
+   - **D** → propose moving back to YELLOW or RED immediately.
+
+6. **Overall autonomy level** for the domain, from 1 (least) to 5 (most):
+
+   - 5: every pattern graded A with at least 10 samples.
+   - 4: at least 70% of patterns graded A, the rest B.
+   - 3: a mix of A, B, and C.
+   - 2: mostly C, or any D without harm.
+   - 1: any serious error, or a D pattern touching safety or money.
+
+## Autonomy Report
+
+Deliver this compact report:
+
+- **Evidence:** the patterns analyzed and the samples per pattern.
+- **Grades:** a table — pattern, samples, OK, corrected, errors, grade.
+- **Mission and channel grades:** the same A/B/C/D applied per channel and
+  per mission, when the log allows it.
+- **Proposed moves:** each suggestion as the exact `decisions.md` line to add
+  or change, with the evidence that justifies it.
+- **Autonomy level:** the overall level and what it means.
+- **No move is automatic:** the human edits `decisions.md`; the grader only
+  proposes.
+
+## Worked example
+
+The log says: "noted client phone numbers" ran 25 times, verified OK 24, one
+correction (wrong field); "sent order to kitchen" 12 times, all OK; "loan
+quote" always proposed (YELLOW), 8 approvals.
+
+- note phone numbers: B (24/25) → keep GREEN, watch the wrong-field error.
+- send order to kitchen: A (12/12) → propose moving it to GREEN.
+- loan quote: C (8 samples, still YELLOW) → keep YELLOW; revisit at 20.
+
+## Management Summary (for owners)
+
+When the human asks for a "summary", "resumen", "weekly report", or invokes
+`/summary`, produce the one-page management report instead of the full
+grading:
+
+- **Period:** the dates covered.
+- **Totals:** sessions, automatic actions (GREEN + SEMI-AUTOMATIC),
+  proposals (approved / adjusted / rejected), corrections, and errors.
+- **Per worker:** one row each — sessions, automatic actions, approval rate,
+  corrections, autonomy level, and one line on what that worker could
+  improve.
+- **Sector KPIs:** computed from the log using the KPI definition file when
+  present (`kpi.md` in the workspace, `.dsh/kpi.md`, or `~/.dsh/kpi.md`);
+  otherwise show the generic KPIs (autonomy level, approval rate,
+  correction rate, error rate).
+- **Suggestions:** the top three improvements, each tied to evidence from
+  the log.
+- **Plain language:** the summary must be readable by a non-technical owner.
+
+## Sector KPIs
+
+A KPI definition file maps business metrics to log evidence. Generic KPIs
+are always available:
+
+- Autonomy level (1–5)
+- Proposal approval rate (approved / proposals)
+- Correction rate (corrections / automatic actions)
+- Error rate (errors / automatic actions)
+- Interpretation sessions (translated conversations)
+
+Sector-specific templates live in `docs/` (for example `kpi-restaurant.md`
+measures service speed through log timestamps; a hotel measures check-in
+time; a clinic measures appointment handling). When a `kpi.md` file exists,
+follow it and report each KPI with its value and its trend.
+
+## Accept modes
+
+Every pattern also gets an accept mode, mirroring the super-agent's
+observe/propose/execute ladder:
+
+- **OBSERVE** — the pattern is only logged, never executed (new or risky).
+- **PROPOSE** — executed only as a proposal the human approves.
+- **EXECUTE** — executed automatically (GREEN) with verification flags.
+
+Propose moves between modes with the same evidence rules as tier moves.
+
+## Developing sector KPIs
+
+When the owner wants their own metrics, co-develop them in three steps:
+
+1. Ask what the business measures and what hurts (for example waiting
+   time).
+2. Map each metric to evidence the log can provide (timestamps, decisions,
+   counts).
+3. Write the KPI file (`kpi.md`) as a table — KPI | definition | evidence —
+   and from then on the Management Summary reports them with trends.
+
+## Rules
+
+- The grader proposes; the human decides. It never edits `decisions.md`.
+- Small samples never justify more autonomy: C stays C.
+- Any error touching safety, credentials, or money resets the pattern to
+  YELLOW or RED and lowers the overall level to 1.
+- Grades quote evidence; nothing is estimated or invented.

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# @javierfrancoleal/autonomy-grader — J.Franco's governance layer.
+# Inserts the skill provider into the host plane of the Cordis tree. The
+# /grade command is registered at runtime when the host command registry
+# resolves.
+- insert:
+    - id: autonomy-grader
+      name: '@javierfrancoleal/autonomy-grader'

package/icon.svg

@@ -0,0 +1,9 @@
+<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 44 a20 20 0 0 1 40 0" fill="none" stroke="#ffffff" stroke-width="5"/>
+  <path d="M32 44 L40 30" stroke="#ffffff" stroke-width="5" stroke-linecap="round"/>
+  <circle cx="32" cy="44" r="4" fill="#ffffff"/>
+  <circle cx="16" cy="40" r="3.5" fill="#22C55E"/>
+  <circle cx="32" cy="34" r="3.5" fill="#FACC15"/>
+  <circle cx="48" cy="40" r="3.5" fill="#EF4444"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,98 @@
+// @javierfrancoleal/autonomy-grader — governance layer of the J.Franco agentic
+// workflow. Created by J.Franco. Registers the autonomy-grader skill provider
+// on the host skill registry and, when the host command registry is
+// available, the /grade command.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "jfranco-autonomy-grader";
+const SKILL_BODY_URL = new URL("../assets/autonomy-grader.md", import.meta.url);
+const RESOURCE_BASE = {
+  kind: "directory",
+  path: fileURLToPath(new URL("../assets/", import.meta.url)),
+};
+
+const CANDIDATE = {
+  name: "autonomy-grader",
+  description: "The governance layer of the J.Franco agentic workflow: grades the reliability of automatic decisions (A/B/C/D) from the supervision log, proposes tier moves for decisions.md, and computes the overall autonomy level 1-5. The human approves every change.",
+  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 = "autonomy-grader";
+
+/** Service required by the bundled provider. */
+const inject = ["skills"];
+
+/** Briefing returned by the /grade command. */
+const GRADE_BRIEFING = [
+  "Autonomy grading ON.",
+  "I will read the supervision log, grade every automatic action pattern",
+  "(A/B/C/D), and propose tier moves for decisions.md.",
+  "I only propose — you approve every change.",
+].join(" ");
+
+/** Briefing returned by the /summary command. */
+const SUMMARY_BRIEFING = [
+  "Management Summary ON.",
+  "I will read the supervision log and produce the one-page report: totals,",
+  "per-worker table, sector KPIs, and the top three improvements.",
+  "Plain language, ready for the owner.",
+].join(" ");
+
+/** Register the bundled skill provider on ctx.skills, and the /grade and
+ *  /summary commands on the host command registry when it resolves. */
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider);
+  const commands = ctx.get("commands");
+  if (commands !== undefined) {
+    commands.register({
+      // Branded ids are identity strings at runtime; this id names the owner.
+      definitionId: "@javierfrancoleal/autonomy-grader",
+      name: "grade",
+      description: "Grade the reliability of automatic decisions and propose tier moves",
+      input: {
+        hint: "[optional: a specific pattern or domain to grade]",
+        attachments: true,
+      },
+      handler: () => ({ text: GRADE_BRIEFING }),
+    });
+    commands.register({
+      definitionId: "@javierfrancoleal/autonomy-grader",
+      name: "summary",
+      description: "One-page management summary for the owner: totals, per-worker table, KPIs, suggestions",
+      input: {
+        hint: "[optional: a period, e.g. 'this week']",
+        attachments: true,
+      },
+      handler: () => ({ text: SUMMARY_BRIEFING }),
+    });
+  }
+}
+
+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": "Autonomie-Bewerter",
+    "description": "Bewertet die Zuverlässigkeit automatischer Entscheidungen anhand des Überwachungsprotokolls und schlägt Stufenwechsel vor — der Eigentümer genehmigt. Governance-Ebene."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Autonomy Grader",
+    "description": "Grades the reliability of automatic decisions from the supervision log and proposes tier moves — the human approves. Governance layer of the agentic workflow."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Calificador de Autonomía",
+    "description": "Califica la fiabilidad de las decisiones automáticas según el registro de supervisión y propone mover niveles — el dueño aprueba. Capa de gobierno del flujo."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Évaluateur d’Autonomie",
+    "description": "Note la fiabilité des décisions automatiques à partir du journal de supervision et propose des changements de niveau — le propriétaire approuve. Couche de gouvernance du flux."
+  }
+}

package/locale/it.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Valutatore di Autonomia",
+    "description": "Valuta l’affidabilità delle decisioni automatiche dal registro di supervisione e propone spostamenti di livello — approva il proprietario. Livello di governance del flusso."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "自律性グレーダー",
+    "description": "監督ログから自動決定の信頼性を評価し、階層変更を提案——オーナーが承認。フローのガバナンス層。"
+  }
+}

package/locale/ko.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "자율성 평가기",
+    "description": "감독 기록에서 자동 결정의 신뢰성을 평가하고 단계 변경을 제안 — 소유자가 승인합니다. 흐름의 거버넌스 계층."
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Avaliador de Autonomia",
+    "description": "Avalia a confiabilidade das decisões automáticas a partir do registro de supervisão e propõe mudanças de nível — o dono aprova. Camada de governança do fluxo."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "自主性评分器",
+    "description": "根据监督记录评估自动决策的可靠性，并提出层级调整——由负责人批准。流程的治理层。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@javierfrancoleal/autonomy-grader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Governance layer of the J.Franco agentic workflow: grades the reliability of automatic decisions from the supervision log and proposes tier moves — the human approves every change.",
+  "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"
+    }
+  },
+  "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-autonomy-grader"
+  },
+  "homepage": "https://github.com/JavierFrancoLeal/jfranco-agentic-suite",
+  "keywords": [
+    "deepseek-harness",
+    "agentic-workflow",
+    "super-agent",
+    "ai-assistant",
+    "accountability",
+    "plugins"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}