gaslighting-engine 0.1.0

package/dist/utils/banner.js

@@ -0,0 +1,49 @@
+export const brandName = "Gaslighting-engine";
+export function printBanner(label) {
+    console.log(renderBanner(label));
+}
+export function renderBanner(label = "PROJECT DISCIPLINE RUNTIME") {
+    return `${ludgiAscii}
+${engineAscii}
+${operatorAscii}
+${brandName.toUpperCase()} // ${label}
+`;
+}
+const ludgiAscii = String.raw `
+ _       _   _  ____   ____ ___
+| |     | | | ||  _ \ / ___|_ _|
+| |     | | | || | | | |  _ | |
+| |___  | |_| || |_| | |_| || |
+|_____|  \___/ |____/ \____|___|
+`;
+const engineAscii = String.raw `
+        _________              .__  .__       .__     __  .__
+       /   _____/____    ______|  | |__| ____ |  |___/  |_|__| ____    ____
+       \_____  \\__  \  /  ___/|  | |  |/ ___\|  |  \   __\  |/    \  / ___\
+       /        \/ __ \_\___ \ |  |_|  / /_/  >   Y  \  | |  |   |  \/ /_/  >
+      /_______  (____  /____  >|____/__\___  /|___|  /__| |__|___|  /\___  /
+              \/     \/     \/        /_____/      \/             \//_____/
+                         ENGINE // NO FAKE COMPLETION
+`;
+const operatorAscii = String.raw `
+                         ______________________
+                    _.-""                      ""-._
+                 .-"      .--.          .--.       "-.
+               .'        /####\        /####\         '.
+              /         |######|      |######|          \
+             /      ____\####/________\####/____         \
+            |     .'      ""     ____     ""     '.       |
+            |    /   .--------.-"    "-.--------.  \      |
+            |   |   /  .====.  \______/  .====.  \  |     |
+            |   |  |  [######]  .----.  [######]  | |     |
+            |   |  |    """"   / .--. \   """"    | |     |
+            |   |   \_________/ /____\ \_________/  |     |
+             \  |        ___  .'      '.  ___        |    /
+              \ |    _.-"   ""-.____.-""   "-._     |   /
+               '| .-"     ________________     "-.  | .'
+                 \     .-"  __          __ "-.      /
+                  '._ /   .'  '.      .'  '.  \ _.'
+                     /___/  /\  \____/  /\  \___\
+                    /___/__/  \________/  \__\___\
+                   /______/    DISCIPLINE   \______\
+`;

package/dist/utils/date.js

@@ -0,0 +1,6 @@
+export function isoDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = `${date.getMonth() + 1}`.padStart(2, "0");
+    const day = `${date.getDate()}`.padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}

package/dist/utils/file.js

@@ -0,0 +1,24 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function variantName(filename) {
+    if (filename.endsWith(".md"))
+        return filename.replace(/\.md$/, ".new.md");
+    return `${filename}.new`;
+}
+export function writeDocs(targetDir, docs, force = false, dryRun = false) {
+    return docs.map((doc) => {
+        const intended = join(targetDir, doc.filename);
+        const exists = existsSync(intended);
+        const finalName = exists && !force ? variantName(doc.filename) : doc.filename;
+        const finalPath = join(targetDir, finalName);
+        if (dryRun)
+            return { filename: finalName, status: "dry_run" };
+        mkdirSync(dirname(finalPath), { recursive: true });
+        writeFileSync(finalPath, doc.content, "utf8");
+        if (exists && force)
+            return { filename: finalName, status: "overwritten" };
+        if (exists)
+            return { filename: finalName, status: "created_variant" };
+        return { filename: finalName, status: "created" };
+    });
+}

package/dist/utils/logger.js

@@ -0,0 +1,27 @@
+import { printBanner } from "./banner.js";
+export function printSummary(analysis, modeLines, results) {
+    printBanner("DOCUMENT GENERATOR");
+    console.log(`Detected project type: ${analysis.projectType}`);
+    console.log(`Confidence: ${analysis.confidence}`);
+    console.log("Detected stack hints:");
+    if (analysis.detectedStackHints.length === 0)
+        console.log("- none");
+    for (const hint of analysis.detectedStackHints)
+        console.log(`- ${hint}`);
+    console.log("\nMode:");
+    for (const line of modeLines)
+        console.log(`- ${line}`);
+    console.log("\nCreated:");
+    for (const result of results) {
+        const suffix = result.status === "created_variant"
+            ? " (existing file preserved)"
+            : result.status === "overwritten"
+                ? " (overwritten)"
+                : result.status === "dry_run"
+                    ? " (dry run)"
+                    : "";
+        console.log(`- ${result.filename}${suffix}`);
+    }
+    console.log('\nNext:\nOpen Codex and say:\n');
+    console.log('"Read GASLIGHTING.md, PRD.md, STACK_POLICY.md, MISSING_INFO.md, ASSUMPTIONS.md, DECISION_LOG.md, MEMORY.md, and AGENTS.md. Implement the MVP without shrinking scope, without TODO escape, and without fake completion."');
+}

package/dist/utils/markdown.js

@@ -0,0 +1,6 @@
+export function list(items) {
+    return items.map((item) => `- ${item}`).join("\n");
+}
+export function quote(value) {
+    return value.replaceAll("|", "\\|");
+}

package/docs/codex-usage.md

@@ -0,0 +1,58 @@
+# Codex Usage
+
+## Recommended Install
+
+Install the Codex-optimized project files:
+
+```bash
+npx gaslighting-engine codex-install --force
+```
+
+This installs:
+
+- `.agents/skills/gaslighting/SKILL.md`
+- `.agents/skills/gaslighting/agents/openai.yaml`
+- `.codex/skills/gaslighting/SKILL.md`
+- `.codex/skills/gaslighting/agents/openai.yaml`
+- `.agents/prompts/gaslighting.md`
+- `.codex/prompts/gaslighting.md`
+- `CODEX_GASLIGHTING.md`
+
+Then use the skill in Codex:
+
+```txt
+$gaslighting
+```
+
+or:
+
+```txt
+Use the gaslighting skill.
+```
+
+Some Codex app versions also show enabled skills in the slash command list. If `/gaslighting` does not appear, use `$gaslighting`.
+
+Check the install:
+
+```bash
+npx gaslighting-engine codex-doctor
+```
+
+## Generate Discipline Docs
+
+Generate documents:
+
+```bash
+gaslighting-engine "I want to build a hospital website."
+```
+
+Then ask Codex:
+
+```txt
+Read GASLIGHTING.md, PRD.md, STACK_POLICY.md, MISSING_INFO.md, ASSUMPTIONS.md, DECISION_LOG.md, MEMORY.md, and AGENTS.md.
+Implement the MVP without shrinking scope, without TODO escape, and without fake completion.
+```
+
+Codex should treat `AGENTS.md` as project guidance and `GASLIGHTING.md` as the anti-escape contract.
+
+The CLI also generates Codex Skill files, prompt fallback files, and `CODEX_GASLIGHTING.md` so the workflow still works when a specific Codex surface does not expose a custom slash entry.

package/docs/examples.md

@@ -0,0 +1,22 @@
+# Examples
+
+Included examples:
+
+- `examples/hospital-homepage`
+- `examples/ecommerce`
+- `examples/landing-page`
+
+Regenerate them with:
+
+```bash
+npm run build
+node dist/index.js "I want to build a hospital website." --path examples/hospital-homepage --force
+node dist/index.js "Build an ecommerce MVP with product catalog, cart, checkout, and admin orders." --type ecommerce --path examples/ecommerce --force
+node dist/index.js "Build a landing page for a new service that captures leads." --type landing_page --path examples/landing-page --force
+```
+
+Published usage:
+
+```bash
+npx gaslighting-engine "I want to build a hospital website."
+```

package/docs/philosophy.md

@@ -0,0 +1,17 @@
+# Philosophy
+
+Gaslighting-engine exists because AI coding agents often confuse presentation with completion.
+
+The generated documents force an agent to preserve scope, document uncertainty, and declare incomplete work honestly.
+
+The pressure target is AI-agent behavior, not humans.
+
+Core doctrine:
+
+- Do the work.
+- Do not pretend.
+- Do not shrink the scope.
+- Do not hide behind examples.
+- Do not leave TODOs as fake implementation.
+- If something is unfinished, say it is unfinished.
+- Fake completion is the worst failure.

package/docs/research.md

@@ -0,0 +1,54 @@
+# Research Notes
+
+Gaslighting-engine now treats context as a layered system instead of a single prompt.
+
+## Codex Findings
+
+- Codex reads `AGENTS.md` before work and layers global/project guidance.
+- Codex Skills package reusable workflow instructions, references, and scripts. Skills are available in CLI, IDE, and app surfaces.
+- Codex App supports explicit Skill invocation with `$skill-name`; current app docs also state enabled skills can appear in the slash command list.
+- Codex Memories can carry stable preferences and recurring workflows forward, but required team guidance should remain in checked-in files like `AGENTS.md`.
+- Chronicle can enrich memories from screen context, but it is opt-in, platform-limited, and carries prompt-injection and privacy risks.
+- Codex slash commands are strong for keyboard-first control, but custom slash-command availability differs by surface/version. The tool therefore treats `$gaslighting` and Skill metadata as the reliable path, while prompt files are fallback helpers.
+- Codex Skill UI metadata can live in `agents/openai.yaml`, so generated skills include this file for better list/chip display where supported.
+
+Sources:
+
+- https://developers.openai.com/codex/guides/agents-md
+- https://developers.openai.com/codex/skills
+- https://developers.openai.com/codex/memories
+- https://developers.openai.com/codex/memories/chronicle
+- https://developers.openai.com/codex/guides/slash-commands
+
+## Hermes-Style Memory
+
+Hermes Agent popularized a very explicit memory shape: persistent files for identity, user model, and project facts. The useful idea for this project is not copying Hermes. The useful idea is making memory inspectable, editable, and file-backed.
+
+Gaslighting-engine applies this by generating `MEMORY.md`:
+
+- stable project facts
+- workflow preferences
+- known agent failure patterns
+- contradiction handling
+- no-secrets rule
+
+## Hades-Style Audit
+
+The useful Hades idea is ruthless cleanup with an audit ledger: remove dead code, suppressions, fake structure, and unverified claims, but make the operation explainable.
+
+Gaslighting-engine applies this as:
+
+- Hades-style audit rules in `MEMORY.md`
+- no fake completion in `GASLIGHTING.md`
+- decision traceability in `DECISION_LOG.md`
+- doctor checks for required discipline files
+
+## Product Decision
+
+The UX should be:
+
+```bash
+gaslighting-engine "what I want to build"
+```
+
+Options should be escape hatches, not required ceremony.

package/examples/ecommerce/.codex/prompts/gaslighting.md

@@ -0,0 +1,30 @@
+# /gaslighting
+
+Read the Gaslighting-engine project-control files before doing any work:
+
+1. `GASLIGHTING.md`
+2. `PRD.md`
+3. `STACK_POLICY.md`
+4. `MISSING_INFO.md`
+5. `ASSUMPTIONS.md`
+6. `DECISION_LOG.md`
+7. `AGENTS.md`
+8. `MEMORY.md`
+
+Then execute the user's requested implementation.
+
+Rules:
+
+- Preserve the full requested scope.
+- Make reasonable assumptions and document them.
+- Do not use TODO comments as fake implementation.
+- Do not implement only representative examples.
+- Do not say "the rest follows the same pattern."
+- Do not call scaffolding completion.
+- Do not call placeholders implementation.
+- Do not over-engineer.
+- Record stable project facts in `MEMORY.md`.
+- Record product and technical decisions in `DECISION_LOG.md`.
+- If something is incomplete, declare it explicitly.
+
+Before claiming completion, perform the self-audit in `GASLIGHTING.md`.

package/examples/ecommerce/.codex/skills/gaslighting/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gaslighting
+description: Generate or update strict project discipline documents for Codex and AI coding agents. Use when a user asks to initialize Gaslighting, create GASLIGHTING.md/PRD.md/AGENTS.md discipline files, preserve full project scope, prevent TODO escape, prevent fake completion, or turn vague project intent into actionable control documents.
+---
+
+# Gaslighting-engine Skill
+
+You are a project-discipline generator for AI coding agents.
+
+When a user gives a vague project request, do not stop and ask a long list of questions.
+
+Instead:
+
+1. Infer the project type.
+2. Identify the project's core purpose.
+3. Make reasonable assumptions.
+4. Document assumptions clearly.
+5. Mark missing information clearly.
+6. Generate `GASLIGHTING.md`.
+7. Generate `PRD.md`.
+8. Generate `ASSUMPTIONS.md`.
+9. Generate `MISSING_INFO.md`.
+10. Generate `DECISION_LOG.md`.
+11. Generate `STACK_POLICY.md`.
+12. Generate or update `AGENTS.md`.
+
+## Hardcore Discipline Rule
+
+The generated documents must prevent escape behavior.
+
+Explicitly forbid:
+
+- implementing only representative examples
+- leaving TODOs instead of implementation
+- saying "the rest can be done similarly"
+- silently reducing requested scope
+- pretending the task is complete
+- replacing implementation with explanation
+- creating empty placeholders
+- skipping repetitive items because they are repetitive
+- treating structure as completion
+- treating direction as delivery
+
+The agent must either:
+
+1. complete the full requested scope, or
+2. clearly declare what is incomplete.
+
+Never allow fake completion.
+
+Never allow scope shrinkage.
+
+Never allow TODO-based escape.
+
+## Missing Information Rule
+
+Missing information is not a free excuse to stop.
+
+Classify missing information as:
+
+- Confirmed
+- Assumed
+- Missing but non-blocking
+- Missing and risky
+- Missing and blocking
+
+Only truly blocking information may stop implementation.
+
+## Default Tech Policy
+
+For web projects, prefer:
+
+- Next.js
+- TypeScript
+- Tailwind CSS
+- shadcn/ui
+- PostgreSQL
+- NeonDB or Supabase
+- Vercel
+- Vercel Blob or Cloudflare R2
+- GA4 + Google Tag Manager when analytics are needed
+- Resend or equivalent when email is needed
+
+Avoid over-engineering.
+
+## Output Rule
+
+Create real markdown files.
+
+Do not only explain.
+
+Do not produce a plan without files.
+
+Do not say what should be done.
+
+Generate the actual project discipline documents.

package/examples/ecommerce/.codex/skills/gaslighting/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Gaslighting-engine"
+  short_description: "Generate strict Codex project discipline docs"
+  brand_color: "#111827"
+  default_prompt: "Use $gaslighting to generate Gaslighting-engine discipline documents before implementation."
+
+policy:
+  allow_implicit_invocation: true