@nac3/forge-cli 1.0.57 → 1.0.59

package/dist/chat/tools/pizarron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pizarron.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/pizarron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGrE,eAAO,MAAM,qBAAqB,EAAE,QAkEnC,CAAC;AAMF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,EACD,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,UAAU,CAAC,CA4DrB"}
+{"version":3,"file":"pizarron.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/pizarron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGrE,eAAO,MAAM,qBAAqB,EAAE,QAkEnC,CAAC;AAMF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,EACD,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,UAAU,CAAC,CAqErB"}

package/dist/chat/tools/pizarron.js

@@ -1,4 +1,4 @@
-import { maybePromoteFlow } from '../flow_bpmn.js';
+import { decideFlowTab } from '../flow_bpmn.js';
 export const SHOW_IN_PIZARRON_SPEC = {
     name: 'forge_show_in_pizarron',
     description: 'Surface STRUCTURED CONTENT (code, table, markdown doc, '
@@ -104,14 +104,23 @@ export async function runShowInPizarron(args, _ctx) {
             display: 'too long',
         };
     }
-    /* Enforce the KIND SELECTION rule server-side: a `graph` whose title reads
-     * like a flow/proceso is promoted to a real BPMN diagram. Some brains ignore
-     * the always-on doctrine and keep drawing flows as force-directed webs. */
+    /* Enforce the KIND SELECTION rule server-side: a `graph` that is really a
+     * flow/proceso. First time -> reject with a nudge so the brain redoes it as
+     * native BPMN (B); on reincidence -> convert deterministically (A). Some
+     * brains ignore the always-on doctrine and keep drawing flows as webs. */
     {
-        const promoted = maybePromoteFlow({ kind, content, title });
-        if (promoted.promoted) {
-            kind = promoted.kind;
-            content = promoted.content;
+        const decision = decideFlowTab({ kind, content, title });
+        if (decision.action === 'reject') {
+            return {
+                tool: SHOW_IN_PIZARRON_SPEC.name,
+                is_error: true,
+                result: { error: decision.message },
+                display: 'flow-as-graph -> nudged to bpmn',
+            };
+        }
+        if (decision.action === 'convert') {
+            kind = decision.kind;
+            content = decision.content;
         }
     }
     /* Generate a stable-ish item id for the panel to use as a

package/dist/chat/tools/pizarron.js.map

@@ -1 +1 @@
-{"version":3,"file":"pizarron.js","sourceRoot":"","sources":["../../../src/chat/tools/pizarron.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pizarron.js","sourceRoot":"","sources":["../../../src/chat/tools/pizarron.ts"],"names":[],"mappings":"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"}

package/dist/docs/doctrine/concurrency-scale.md

@@ -0,0 +1,54 @@
+# Concurrency & scale doctrine
+
+Every application Forge designs MUST be sized to its expected
+concurrency from day one. Scale is a RELEVAMIENTO input, not an
+afterthought bolted on when the app falls over.
+
+## 1. Ask it during requirements
+
+During the greenfield relevamiento -- and when scoping a corrective /
+evolutive change that touches a load-bearing path -- ASK, before
+choosing an architecture:
+
+- Peak SIMULTANEOUS users / requests? Give an order of magnitude:
+  tens, hundreds, thousands, 10k+.
+- Read-heavy or write-heavy? Steady or bursty (spikes)?
+- Latency budget: interactive (< ~200 ms) or batch/async?
+- Growth horizon: will it 10x within a year?
+- Consistency needs: strong (banking) or eventual (feeds)?
+
+If the user does not know, PROPOSE a reasonable default AND write the
+assumption explicitly in the spec / `<root>/.forge/sumi-context.md`.
+Never silently assume "a handful of users".
+
+## 2. Design a multi-layer architecture with no bottleneck at any tier
+
+Pick the layers that the target number actually needs, and make each
+one non-blocking:
+
+- Client: pagination, debounce, optimistic UI, local cache -- do not
+  fetch the world on every keystroke.
+- Edge / CDN: serve static + cacheable responses close to the user.
+- App tier: STATELESS request handlers so nodes scale horizontally.
+  No in-process session/user state that pins a user to one node
+  (put it in a shared store / signed token).
+- Concurrency control: connection pools sized to the DB; queues +
+  backpressure to absorb spikes; idempotency keys for retried writes;
+  rate limits / circuit breakers on hot paths.
+- Data tier (the usual bottleneck): indexed queries; read replicas
+  for read-heavy loads; a cache (Redis / KV) in front of hot reads;
+  async jobs for slow writes; partition / shard ONLY when the numbers
+  demand it.
+- Realtime: fan out via a broker (Redis pub/sub, a queue, a hub), not
+  an N-app-node polling loop.
+
+## 3. Proportionality (do not gold-plate)
+
+Match the architecture to the number. A 20-user internal tool gets a
+simple single-tier design -- adding sharding + a message broker there
+is a defect too. A 10k-concurrent public app gets the full multi-layer
+treatment. The rule is "no bottleneck AND no gold-plating", sized to
+the stated concurrency.
+
+Record the target concurrency and the tier decisions in the spec so
+they are traceable and can be revisited when the number changes.

package/dist/docs/doctrine/pizarron.md

@@ -92,13 +92,23 @@ business flow with kind="graph". The user asks for a FLUJO and
 gets a force-directed node web instead of a BPMN diagram.
 
 SERVER-SIDE ENFORCEMENT (src/chat/flow_bpmn.ts): because some
-brains ignore this rule anyway, the server catches it. When a
-create-tab arrives with kind="graph" and a TITLE that reads like a
-flow (flujo / proceso / flowchart / workflow / "los pasos de" /
-BPMN / ...), the server converts the {nodes,edges} into a BPMN
-{nodes,flows} model (synthetic start/end events; a labelled
-2-way branch becomes an exclusive gateway) and renders it as a
-real BPMN diagram. This is a safety net, NOT a licence to keep
-sending graph -- always classify the kind yourself. Relationship
-graphs (title has "grafo/relaciones/dependencias") are left
-untouched.
+brains ignore this rule anyway, the server catches it. A graph is
+treated as a flow when its TITLE reads like one (flujo / flow /
+flowchart / proceso / cursograma / pipeline / etapas / ciclo /
+journey / "grafico de procesos" / BPMN / ...) OR when its STRUCTURE
+is an ordered, acyclic, sparse sequence or a labelled-decision graph
+(so a flow with a neutral title like "Alta de cliente" is caught
+too). Then, in two layers:
+  (B) the FIRST time, the create-tab is REJECTED with a nudge telling
+      you to re-create it as kind="bpmn" -- native BPMN with proper
+      startEvent/endEvent, tasks and gateways. Just do it in the same
+      response.
+  (A) if you RESEND the same graph instead of obeying, the server
+      converts it deterministically (synthetic start/end; a labelled
+      2-way branch -> exclusive gateway) so the user NEVER sees an
+      ugly flow, whatever you send.
+Relationship / dependency / hierarchy graphs (title has grafo /
+relaciones / dependencias / organigrama / entidad-relacion, or a
+dense / cyclic structure) are left untouched. This is a safety net,
+NOT a licence to keep sending graph -- always classify the kind
+yourself.

package/dist/semantic_graph/last_change.d.ts

@@ -0,0 +1,9 @@
+/** relPath (posix slashes) -> unix seconds of the file's most recent commit.
+ *  Empty map when git is unavailable / not a repo (caller falls to mtime). */
+export declare function fileLastChangeMap(projectRoot: string): Promise<Map<string, number>>;
+/** Resolve a node's last-change ts: git map by path, else fs mtime, else 0. */
+export declare function nodeLastChange(projectRoot: string, relPath: string, gitMap: Map<string, number>): Promise<number>;
+/** Server-side twin of the panel's graphNodePath: the last path-like
+ *  parenthetical in a node's purpose/detail ("... (src/foo.py)."). */
+export declare function pathFromPurpose(purpose: string): string;
+//# sourceMappingURL=last_change.d.ts.map

package/dist/semantic_graph/last_change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"last_change.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/last_change.ts"],"names":[],"mappings":"AAaA;8EAC8E;AAC9E,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoBnF;AAED,+EAA+E;AAC/E,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChE,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;sEACsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BvD"}

package/dist/semantic_graph/last_change.js

@@ -0,0 +1,93 @@
+/**
+ * Per-file "last change" timestamp for the galaxy graph colouring (Pablo,
+ * 2026-07-05). One `git log` pass yields the most-recent commit time per
+ * tracked file; the filesystem mtime is the fallback for untracked files.
+ * The panel normalises these across nodes and colours newest -> blue,
+ * oldest -> red (full spectrum).
+ *
+ * ASCII-only.
+ */
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** relPath (posix slashes) -> unix seconds of the file's most recent commit.
+ *  Empty map when git is unavailable / not a repo (caller falls to mtime). */
+export function fileLastChangeMap(projectRoot) {
+    return new Promise((resolve) => {
+        execFile('git', ['log', '--format=%ct', '--name-only', '--no-renames'], { cwd: projectRoot, maxBuffer: 128 * 1024 * 1024, windowsHide: true }, (err, stdout) => {
+            const map = new Map();
+            if (err || !stdout) {
+                resolve(map);
+                return;
+            }
+            let ts = 0;
+            for (const raw of String(stdout).split('\n')) {
+                const line = raw.trim();
+                if (!line)
+                    continue;
+                if (/^\d+$/.test(line)) {
+                    ts = parseInt(line, 10);
+                    continue;
+                }
+                const rel = line.replace(/\\/g, '/');
+                if (!map.has(rel))
+                    map.set(rel, ts); // git log is newest-first: first wins
+            }
+            resolve(map);
+        });
+    });
+}
+/** Resolve a node's last-change ts: git map by path, else fs mtime, else 0. */
+export async function nodeLastChange(projectRoot, relPath, gitMap) {
+    if (!relPath)
+        return 0;
+    const rel = relPath.replace(/\\/g, '/');
+    const g = gitMap.get(rel);
+    if (g)
+        return g;
+    try {
+        const st = await stat(join(projectRoot, rel));
+        return Math.floor(st.mtimeMs / 1000);
+    }
+    catch {
+        return 0;
+    }
+}
+/** Server-side twin of the panel's graphNodePath: the last path-like
+ *  parenthetical in a node's purpose/detail ("... (src/foo.py)."). */
+export function pathFromPurpose(purpose) {
+    const d = String(purpose || '');
+    const cands = [];
+    let i = 0;
+    while (i < d.length) {
+        const open = d.indexOf('(', i);
+        if (open < 0)
+            break;
+        const close = d.indexOf(')', open + 1);
+        if (close < 0)
+            break;
+        cands.push(d.slice(open + 1, close).trim());
+        i = close + 1;
+    }
+    for (let k = cands.length - 1; k >= 0; k--) {
+        let inner = cands[k] || '';
+        if (!inner || inner.length > 240)
+            continue;
+        while (inner.length && '.,;'.indexOf(inner.charAt(inner.length - 1)) >= 0)
+            inner = inner.slice(0, -1);
+        const hasSep = inner.indexOf('/') >= 0 || inner.indexOf('\\') >= 0;
+        let hasExt = false;
+        const dot = inner.lastIndexOf('.');
+        if (dot > 0 && dot < inner.length - 1) {
+            const ext = inner.slice(dot + 1);
+            hasExt = ext.length <= 8 && /^[a-z0-9]+$/i.test(ext);
+        }
+        if (!hasSep && !hasExt)
+            continue;
+        if (inner.indexOf(' ') >= 0 && !hasSep)
+            continue;
+        return inner;
+    }
+    return '';
+}
+//# sourceMappingURL=last_change.js.map

package/dist/semantic_graph/last_change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"last_change.js","sourceRoot":"","sources":["../../src/semantic_graph/last_change.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export declare const VERSION = "1.0.57";
+export declare const VERSION = "1.0.59";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export const VERSION = '1.0.57';
+export const VERSION = '1.0.59';
 //# sourceMappingURL=version.js.map

package/docs/doctrine/concurrency-scale.md

@@ -0,0 +1,54 @@
+# Concurrency & scale doctrine
+
+Every application Forge designs MUST be sized to its expected
+concurrency from day one. Scale is a RELEVAMIENTO input, not an
+afterthought bolted on when the app falls over.
+
+## 1. Ask it during requirements
+
+During the greenfield relevamiento -- and when scoping a corrective /
+evolutive change that touches a load-bearing path -- ASK, before
+choosing an architecture:
+
+- Peak SIMULTANEOUS users / requests? Give an order of magnitude:
+  tens, hundreds, thousands, 10k+.
+- Read-heavy or write-heavy? Steady or bursty (spikes)?
+- Latency budget: interactive (< ~200 ms) or batch/async?
+- Growth horizon: will it 10x within a year?
+- Consistency needs: strong (banking) or eventual (feeds)?
+
+If the user does not know, PROPOSE a reasonable default AND write the
+assumption explicitly in the spec / `<root>/.forge/sumi-context.md`.
+Never silently assume "a handful of users".
+
+## 2. Design a multi-layer architecture with no bottleneck at any tier
+
+Pick the layers that the target number actually needs, and make each
+one non-blocking:
+
+- Client: pagination, debounce, optimistic UI, local cache -- do not
+  fetch the world on every keystroke.
+- Edge / CDN: serve static + cacheable responses close to the user.
+- App tier: STATELESS request handlers so nodes scale horizontally.
+  No in-process session/user state that pins a user to one node
+  (put it in a shared store / signed token).
+- Concurrency control: connection pools sized to the DB; queues +
+  backpressure to absorb spikes; idempotency keys for retried writes;
+  rate limits / circuit breakers on hot paths.
+- Data tier (the usual bottleneck): indexed queries; read replicas
+  for read-heavy loads; a cache (Redis / KV) in front of hot reads;
+  async jobs for slow writes; partition / shard ONLY when the numbers
+  demand it.
+- Realtime: fan out via a broker (Redis pub/sub, a queue, a hub), not
+  an N-app-node polling loop.
+
+## 3. Proportionality (do not gold-plate)
+
+Match the architecture to the number. A 20-user internal tool gets a
+simple single-tier design -- adding sharding + a message broker there
+is a defect too. A 10k-concurrent public app gets the full multi-layer
+treatment. The rule is "no bottleneck AND no gold-plating", sized to
+the stated concurrency.
+
+Record the target concurrency and the tier decisions in the spec so
+they are traceable and can be revisited when the number changes.

package/docs/doctrine/pizarron.md

@@ -92,13 +92,23 @@ business flow with kind="graph". The user asks for a FLUJO and
 gets a force-directed node web instead of a BPMN diagram.
 
 SERVER-SIDE ENFORCEMENT (src/chat/flow_bpmn.ts): because some
-brains ignore this rule anyway, the server catches it. When a
-create-tab arrives with kind="graph" and a TITLE that reads like a
-flow (flujo / proceso / flowchart / workflow / "los pasos de" /
-BPMN / ...), the server converts the {nodes,edges} into a BPMN
-{nodes,flows} model (synthetic start/end events; a labelled
-2-way branch becomes an exclusive gateway) and renders it as a
-real BPMN diagram. This is a safety net, NOT a licence to keep
-sending graph -- always classify the kind yourself. Relationship
-graphs (title has "grafo/relaciones/dependencias") are left
-untouched.
+brains ignore this rule anyway, the server catches it. A graph is
+treated as a flow when its TITLE reads like one (flujo / flow /
+flowchart / proceso / cursograma / pipeline / etapas / ciclo /
+journey / "grafico de procesos" / BPMN / ...) OR when its STRUCTURE
+is an ordered, acyclic, sparse sequence or a labelled-decision graph
+(so a flow with a neutral title like "Alta de cliente" is caught
+too). Then, in two layers:
+  (B) the FIRST time, the create-tab is REJECTED with a nudge telling
+      you to re-create it as kind="bpmn" -- native BPMN with proper
+      startEvent/endEvent, tasks and gateways. Just do it in the same
+      response.
+  (A) if you RESEND the same graph instead of obeying, the server
+      converts it deterministically (synthetic start/end; a labelled
+      2-way branch -> exclusive gateway) so the user NEVER sees an
+      ugly flow, whatever you send.
+Relationship / dependency / hierarchy graphs (title has grafo /
+relaciones / dependencias / organigrama / entidad-relacion, or a
+dense / cyclic structure) are left untouched. This is a safety net,
+NOT a licence to keep sending graph -- always classify the kind
+yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.0.57",
+  "version": "1.0.59",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",