@agjs/tsforge 0.3.2 → 0.3.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/scripts/sweep.ts

@@ -87,6 +87,8 @@ function variantToEnvVars(variant: IFeatureVariant): Record<string, string> {
       envVars.TSFORGE_HASHLINE = state === "1" ? "1" : "0";
     } else if (dim === "lsp_write_feedback") {
       envVars.TSFORGE_LSP_WRITE_FEEDBACK = state === "1" ? "1" : "0";
+    } else if (dim === "simplicity") {
+      envVars.TSFORGE_SIMPLICITY = state === "1" ? "1" : "0";
     }
     // else: unknown dimension, skip
   }

package/src/config/config.constants.ts

@@ -6,4 +6,5 @@ export const ENV_FLAG = {
   legacyFeedback: "TSFORGE_LEGACY_FEEDBACK",
   noAstgrep: "TSFORGE_NO_ASTGREP",
   forceTools: "TSFORGE_FORCE_TOOLS",
+  simplicity: "TSFORGE_SIMPLICITY",
 } as const;

package/src/config/flags.ts

@@ -29,4 +29,8 @@ export const flags = {
    *  (A/B control, default ON — set to "0" to disable). */
   lspWriteFeedback: (): boolean =>
     process.env.TSFORGE_LSP_WRITE_FEEDBACK !== "0",
+  /** Scratch-utility simplicity guidance — appends a "shortest correct solution"
+   *  block to the build prompt for from-scratch, non-web tasks (A/B control,
+   *  default OFF until a sweep validates it). */
+  simplicity: (): boolean => isOn(ENV_FLAG.simplicity),
 };

package/src/loop/prompt/index.ts

@@ -1,2 +1,9 @@
-export { SYSTEM, CHAT_SYSTEM, COMPACT_SYSTEM, seedPrompt } from "./prompt";
+export {
+  SYSTEM,
+  CHAT_SYSTEM,
+  COMPACT_SYSTEM,
+  SCRATCH_SIMPLICITY_GUIDANCE,
+  buildSystemPrompt,
+  seedPrompt,
+} from "./prompt";
 export { renderFileSection, exportedSymbols } from "./project-map";

package/src/loop/prompt/prompt.ts

@@ -1,7 +1,8 @@
 import type { ITask } from "../../spec";
 import type { IFileView } from "../../lib/fs";
-import { PACK_REGISTRY } from "../../stack-detection";
+import { PACK_REGISTRY, isWebStack } from "../../stack-detection";
 import type { IStackProfile } from "../../stack-detection";
+import { flags } from "../../config";
 import { renderFileSection } from "./project-map";
 
 /** The implement-agent system prompt: who it is, the tools, and the strict-TS
@@ -16,6 +17,40 @@ export const SYSTEM = [
   "The gate is `tsc` strict + eslint with every rule an error, so write TypeScript that satisfies it: interfaces are `I`-prefixed; `===`; no `var`; never the non-null `!` — guard index access (`const x = arr[i]; if (x === undefined) {...}`); no `any` and no `as` — type every parameter (e.g. `.reduce((acc: number, r: number) => …, 0)`); explicit boolean conditions. When the gate flags errors in read-only files (tests/types), they come from your editable file being missing or wrong-shaped and vanish once it's correct — don't edit them.",
 ].join("\n");
 
+/** Appended to SYSTEM for from-scratch, NON-web utility builds when the simplicity
+ *  flag is on. Pushes the model toward the shortest correct solution — the axis the
+ *  gate is blind to (it checks correctness, never concision). Carve-outs keep it
+ *  from fighting the gate's hard rules. NOT for web builds (the views/components
+ *  architecture legitimately needs many small files). */
+export const SCRATCH_SIMPLICITY_GUIDANCE = [
+  "SIMPLICITY — write the SHORTEST correct solution that passes the gate:",
+  "  • The task's `files:` are the ceiling — do NOT add modules, classes, or",
+  "    abstractions the task didn't ask for. One focused implementation.",
+  "  • Prefer built-ins and a direct expression over step-by-step temporaries:",
+  "    chain the transforms (`xs.filter(...).map(...)`) instead of naming each",
+  "    intermediate, when it stays readable.",
+  "  • NO narration/step comments ('// Step 1', '// first we…') — the code is the",
+  "    explanation. A comment earns its place only for a non-obvious WHY.",
+  "  • This NEVER overrides the gate: keep `I`-prefixed interfaces, no `as`/`any`/`!`,",
+  "    real validation at trust boundaries, and any test siblings the gate requires.",
+].join("\n");
+
+/** SYSTEM + the simplicity block when it applies, else SYSTEM unchanged. Gated on
+ *  the `simplicity` flag AND a from-scratch (`!hasExistingCode`) NON-web build —
+ *  so it never touches existing-repo edits or web/UI apps. */
+export function buildSystemPrompt(
+  hasExistingCode: boolean,
+  stack: IStackProfile | undefined
+): string {
+  const webish = stack !== undefined && isWebStack(stack);
+
+  if (!flags.simplicity() || hasExistingCode || webish) {
+    return SYSTEM;
+  }
+
+  return `${SYSTEM}\n\n${SCRATCH_SIMPLICITY_GUIDANCE}`;
+}
+
 /**
  * The INTERACTIVE assistant prompt (the CLI's `Session`). Unlike `SYSTEM` — which
  * drives a single task to a gate and is told to "keep going until green" — this

package/src/loop/run.ts

@@ -17,7 +17,7 @@ import type {
 } from "./loop.types";
 import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { flags } from "../config";
-import { SYSTEM, seedPrompt } from "./prompt";
+import { buildSystemPrompt, seedPrompt } from "./prompt";
 import { detectStack } from "../stack-detection";
 import type { TtsrManager } from "./ttsr";
 import {
@@ -295,17 +295,23 @@ export async function runTask(
 
   const editable = await readFiles(cwd, task.files);
   const context = await readFiles(cwd, task.context ?? []);
+
+  // Existing code to navigate? (editable files already have content). Only then
+  // do the LSP nav tools earn their decision-surface cost — see toolsFor(). Also
+  // gates the scratch-simplicity guidance (from-scratch builds only).
+  const hasExistingCode = editable.some((f) => f.content.trim().length > 0);
+
   const messages: IChatMessage[] = [
-    { role: "system", content: SYSTEM },
+    {
+      role: "system",
+      content: buildSystemPrompt(hasExistingCode, stackProfile),
+    },
     {
       role: "user",
       content: seedPrompt(task, editable, context, stackProfile),
     },
   ];
 
-  // Existing code to navigate? (editable files already have content). Only then
-  // do the LSP nav tools earn their decision-surface cost — see toolsFor().
-  const hasExistingCode = editable.some((f) => f.content.trim().length > 0);
   const tools = toolsFor(hasExistingCode);
 
   // Mode-aware reasoning cap: scratch tasks over-think unbounded, so default

package/src/stack-detection/detect.ts

@@ -9,6 +9,21 @@ import {
   type IPackId,
 } from "./packs";
 
+/** The pack ids that identify a WEB (browser UI) build. Used to scope behaviours
+ *  that must NOT apply to web apps (e.g. the scratch-simplicity prompt, whose
+ *  "shortest solution / no extra files" advice fights the views/components
+ *  architecture the web scaffold requires). */
+const WEB_PACK_IDS: readonly string[] = [
+  "react",
+  "react-component-architecture",
+  "tanstack-query",
+];
+
+/** True when the detected stack is a web/browser UI build. */
+export function isWebStack(profile: IStackProfile): boolean {
+  return profile.packs.some((p) => WEB_PACK_IDS.includes(p));
+}
+
 /** Parse package.json and extract deps/devDeps, tolerating missing/invalid JSON. */
 async function loadPackageDeps(cwd: string): Promise<{
   deps: Set<string>;

package/src/stack-detection/index.ts

@@ -1,3 +1,3 @@
 export * from "./stack-detection.types";
-export { detectStack } from "./detect";
+export { detectStack, isWebStack } from "./detect";
 export { PACK_REGISTRY, ALWAYS_ON_PACKS } from "./packs";