@javierfrancoleal/forensics 0.0.0-stage → 1.0.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,25 @@
-# Temporary Holding Version
+---
+description: "The code-forensics organ: trace a feature end to end, read the fossil record, and produce a plain-language dossier."
+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/forensics
+
+Created by **J.Franco**.
+
+## Summary
+
+AI writes the code; the human reconstructs it. The forensics organ is the
+archaeological protocol: identify the layers, trace ONE feature end to
+end, read the fossil record (commits, LEARNINGS, triage, audit), and
+produce a plain-language dossier that lets a non-programmer give correct
+orders.
+
+## Use this plugin
+
+Ask "forensics" or use `/forensics <feature>` (e.g. `/forensics the
+virtual register`).
+
+## License
+
+MIT — see the package license field.

package/assets/forensics.md

@@ -0,0 +1,52 @@
+# Forensics — the code archaeologist
+
+The future of programming: the AI writes the code; the human — with the
+AI's help — reconstructs HOW and WHY it was written. This organ is the
+dig protocol.
+
+## The dig (four layers)
+
+### 1. The strata — identify the layers
+
+For the repository in front of you, name each layer in one line: the UI
+(what humans see), the server/API (what receives orders), the state (what
+is remembered), the logs (what was recorded). Our own suite has a map:
+`docs/ARCHITECTURE.md`.
+
+### 2. The trace — follow one feature end to end
+
+Pick ONE feature (e.g. "the virtual register") and trace its full path:
+
+- UI: the button/input that triggers it.
+- API: the endpoint it calls (method + path).
+- State: the file it writes/reads.
+- Effect: what the user sees next.
+
+Write the trace as a numbered list — no prose walls. If a link in the
+chain is missing, say so: gaps are findings.
+
+### 3. The fossil record — read the history
+
+- `git log` for the file: each commit message is a fossil — what was the
+  INTENT at that moment?
+- `LEARNINGS.md`, `triage.md`, `audit.md`: the incidents that shaped the
+  code (our suite keeps these append-only on purpose).
+- Docs: the design decisions (`INDUSTRIAL-LENS.md`, `NEURO-ANATOMY.md`).
+
+### 4. The dossier — explain in plain language
+
+Produce a dossier with: what it does · how it flows · why each piece
+exists (with the evidence quote) · the risks/gaps · the vocabulary to
+change it. Aim: a non-programmer can give correct orders after reading it.
+
+## Rules
+
+- Evidence first: quote the commit/line, never guess the intent.
+- One feature per dig; depth over breadth.
+- The dossier is a deliverable: append it to the repo docs or the audit
+  log, so the next dig builds on it.
+
+## Why this matters
+
+The code will be written by AI; the VALUE will belong to those who can
+read it. Every dig turns an opaque artifact into an owned asset.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @javierfrancoleal/forensics — J.Franco's code-forensics organ.
+- insert:
+    - id: forensics
+      name: '@javierfrancoleal/forensics'

package/icon.svg

@@ -0,0 +1,7 @@
+<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="M32 12 L32 52 M12 32 L52 32" stroke="#ffffff" stroke-width="3"/>
+  <circle cx="32" cy="32" r="14" fill="none" stroke="#ffffff" stroke-width="3.5"/>
+  <path d="M46 46 C 42 50, 37 52, 32 52" fill="none" stroke="#FACC15" stroke-width="3.5" stroke-linecap="round"/>
+  <circle cx="46" cy="46" r="3" fill="#FACC15"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,56 @@
+// @javierfrancoleal/forensics — an organ of the J.Franco agentic workflow.
+// Created by J.Franco. Registers the forensics skill provider and, when the
+// host command registry is available, the /forensics command.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "javierfrancoleal-forensics";
+const SKILL_BODY_URL = new URL("../assets/forensics.md", import.meta.url);
+const RESOURCE_BASE = { kind: "directory", path: fileURLToPath(new URL("../assets/", import.meta.url)) };
+
+const CANDIDATE = {
+  name: "forensics",
+  description: "The code-forensics organ of the J.Franco agentic workflow: trace one feature end to end, read the fossil record, and produce a plain-language dossier.",
+  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() {
+    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"),
+    };
+  },
+};
+
+const name = "forensics";
+const inject = ["skills"];
+
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider);
+  const commands = ctx.get("commands");
+  if (commands !== undefined) {
+    commands.register({
+      definitionId: "@javierfrancoleal/forensics",
+      name: "forensics",
+      description: "Dig into one feature and explain how and why it was built",
+      input: { hint: "[the feature, e.g. the virtual register]", attachments: true },
+      handler: () => ({ text: "Forensics ON. Name one feature and I will dig: layers, the end-to-end trace, the history that explains it, and a dossier you can order from." }),
+    });
+  }
+}
+
+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": "Code-Forensik",
+    "description": "Verfolgen Sie eine Funktion durchgängig und erklären Sie, wie und warum sie gebaut wurde."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Code Forensics",
+    "description": "Trace one feature end to end and explain how and why it was built."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Forense de Código",
+    "description": "Rastrea una función de punta a punta y explica cómo y por qué se construyó."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Médecine légale du code",
+    "description": "Tracez une fonction de bout en bout et expliquez comment et pourquoi elle a été construite."
+  }
+}

package/locale/it.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Forense del codice",
+    "description": "Traccia una funzione da un capo all'altro e spiega come e perché è stata costruita."
+  }
+}

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": "Forense de Código",
+    "description": "Rastreie uma função de ponta a ponta e explique como e porquê foi construída."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "代码取证",
+    "description": "端到端追踪一个功能，并解释它是如何以及为何构建的。"
+  }
+}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@javierfrancoleal/forensics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The code-forensics organ of the J.Franco agentic workflow: the archaeological protocol for understanding how AI-written code was made — trace a feature end to end, read the fossil record (commits, LEARNINGS, triage, audit), and produce a plain-language dossier. Created by J.Franco.",
+  "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" },
+  "repository": { "type": "git", "url": "git+https://github.com/JavierFrancoLeal/jfranco-agentic-suite.git", "directory": "jfranco-forensics" },
+  "homepage": "https://github.com/JavierFrancoLeal/jfranco-agentic-suite",
+  "keywords": ["deepseek-harness", "agentic-workflow", "super-agent", "code-forensics", "archaeology", "ai-written-code"],
+  "dsh": { "manifestVersion": 1, "bundle": { "patch": "./cordis.patch.yml" } },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/dsh-skill": ">=0.2.1-rc.5" }
+}