diogenes 0.1.2 → 0.1.3

data/docs/gates.md

@@ -0,0 +1,178 @@
+# Gate Reference
+
+The five gates each map to a Ruby principle. A feature must pass all five to proceed. Gates are evaluated in order — failing early is cheaper than failing late.
+
+## Gate 1 — Failure Mode
+
+**Ruby principle:** Least surprise — at scale
+
+**The question:** What happens when this feature is wrong?
+
+This gate isn't asking *if* the AI will be wrong. It will be. The gate asks what failure looks like for a real user at real scale. A wrong restaurant recommendation is recoverable. A wrong medication interaction summary is not.
+
+### Options
+
+| Option | Values | Notes |
+|--------|--------|-------|
+| `severity` | `:recoverable`, `:embarrassing`, `:catastrophic` | Required |
+
+### Pass / Fail
+
+| Severity | Result |
+|----------|--------|
+| `:recoverable` | ✓ PASS — user can identify and recover from a wrong answer |
+| `:embarrassing` | ✓ PASS (with conditions) — wrong answers hurt trust but don't cause harm |
+| `:catastrophic` | ✗ FAIL — wrong answers cause harm that can't be undone |
+
+### Failure message
+
+```text
+Gate 1 (failure_mode) failed.
+severity: :catastrophic — catastrophic failures are not acceptable at scale.
+When this feature is wrong, the user cannot recover without assistance or may
+be actively harmed. Consider a software alternative: clearer UI, explicit error
+states, or rule-based logic with predictable output.
+```
+
+## Gate 2 — User Verifiable
+
+**Ruby principle:** Trust requires verification
+
+**The question:** Can your average user tell when it's wrong?
+
+The calibration gap. If the user lacks the domain knowledge to evaluate the AI's output, you've built a confident-sounding oracle nobody can fact-check. That's not a feature — it's a liability. The AI's confidence doesn't transfer knowledge to the user.
+
+### Options
+
+| Option | Values | Notes |
+|--------|--------|-------|
+| `domain` | `:general`, `:technical`, `:financial`, `:medical`, `:legal` | Required |
+| `user_expertise` | `:novice`, `:intermediate`, `:expert` | Optional, defaults to `:novice` |
+
+### Pass / Fail
+
+| Domain | User Expertise | Result |
+|--------|---------------|--------|
+| `:general` | any | ✓ PASS |
+| `:technical` | `:expert` | ✓ PASS |
+| `:technical` | `:novice`, `:intermediate` | ✗ FAIL |
+| `:financial` | `:expert` | ✓ PASS |
+| `:financial` | `:novice`, `:intermediate` | ✗ FAIL |
+| `:medical` | any | ✗ FAIL |
+| `:legal` | any | ✗ FAIL |
+
+### Failure message
+
+```text
+Gate 2 (user_verifiable) failed.
+domain: :financial, user_expertise: :novice — the average user cannot verify
+financial AI output without domain expertise. A confident wrong answer in a
+financial context creates disputes users can't resolve themselves.
+Consider: display the underlying data alongside any AI interpretation so the
+user can evaluate both.
+```
+
+## Gate 3 — Human in the Loop
+
+**Ruby principle:** Human-centered design, genuinely
+
+**The question:** Is there a human checking — actually checking?
+
+"A human reviews it" sounds responsible until you realize the human is reviewing 400 AI outputs a day and rubber-stamping them. A human in the loop must have the time, context, and authority to actually intervene. Theater is not a gate.
+
+### Options
+
+| Option | Values | Notes |
+|--------|--------|-------|
+| `required` | `true`, `false` | Required. Does this feature need human review? |
+| `capacity` | `:real`, `:theoretical` | Required if `required: true` |
+| `authority` | `true`, `false` | Optional. Can the human actually intervene? Defaults to `true` |
+
+### Pass / Fail
+
+| Required | Capacity | Authority | Result |
+|----------|----------|-----------|--------|
+| `false` | — | — | ✓ PASS — no human review needed |
+| `true` | `:real` | `true` | ✓ PASS |
+| `true` | `:real` | `false` | ✗ FAIL — human can see but not act |
+| `true` | `:theoretical` | any | ✗ FAIL — rubber-stamping is not a loop |
+
+### Failure message
+
+```text
+Gate 3 (human_in_loop) failed.
+capacity: :theoretical — a human review process that doesn't scale to real
+throughput is theater, not a safety gate. If reviewers are rubber-stamping,
+the loop isn't doing the work you think it is.
+Consider: reduce the volume of AI decisions that require review, or invest in
+tooling that makes review genuinely fast and high-confidence.
+```
+
+## Gate 4 — Observability
+
+**Ruby principle:** Craftsmanship — you wouldn't ship a sorting algorithm blind
+
+**The question:** Do you have the monitoring to know when it's going wrong?
+
+Most teams ship AI features with less monitoring than they'd give a sorting algorithm. Without the ability to detect hallucination rates, output drift, or user confusion signals, you don't know what you've shipped. You've released something that can degrade silently.
+
+### Options
+
+| Option | Values | Notes |
+|--------|--------|-------|
+| `monitoring` | `:required`, `:optional`, `:none` | Required |
+| `signals` | array of symbols | Optional. e.g. `[:hallucination_rate, :user_correction_rate, :latency]` |
+
+### Pass / Fail
+
+| Monitoring | Result |
+|------------|--------|
+| `:required` (and signals defined) | ✓ PASS |
+| `:required` (and no signals) | ✗ FAIL — required but no signals defined |
+| `:optional` | ✓ PASS (with warning) |
+| `:none` | ✗ FAIL |
+
+### Failure message
+
+```text
+Gate 4 (observability) failed.
+monitoring: :none — you have no way to know when this feature starts going wrong
+in production. AI output degrades over time as prompts, models, and underlying
+data change. Silent degradation is worse than no feature.
+Consider: define at minimum a user correction rate signal and a weekly review
+cadence before shipping.
+```
+
+## Gate 5 — Right Tool
+
+**Ruby principle:** Convention over configuration — use the boring right answer
+
+**The question:** Is AI the right tool here, or just the exciting one?
+
+This gate exists to give you explicit permission to say no. Sometimes a rule-based system, a good search index, clearer copy, or better UX solves the problem better, cheaper, and more reliably. The framework should make "not AI" a first-class answer, not a fallback.
+
+### Options
+
+| Option | Values | Notes |
+|--------|--------|-------|
+| `alternatives_considered` | `true`, `false` | Required |
+| `alternative_verdict` | `:inferior`, `:equivalent`, `:superior` | Required if `alternatives_considered: true` |
+
+### Pass / Fail
+
+| Alternatives Considered | Alternative Verdict | Result |
+|------------------------|---------------------|--------|
+| `false` | — | ✗ FAIL — you haven't checked |
+| `true` | `:inferior` | ✓ PASS — AI is genuinely the right choice |
+| `true` | `:equivalent` | ✗ FAIL — use the simpler option |
+| `true` | `:superior` | ✗ FAIL — the non-AI solution is better; build that instead |
+
+### Failure message
+
+```text
+Gate 5 (right_tool) failed.
+alternative_verdict: :equivalent — a non-AI solution would serve this need
+equally well, with lower complexity, lower cost, and more predictable behavior.
+Convention over configuration: use the boring right answer.
+The software alternative should be the feature.
+```

data/docs/targets.md

@@ -0,0 +1,11 @@
+# Build Targets
+
+## Claude Code
+
+## Cursor
+
+## Copilot
+
+## Gemini
+
+## Codex

data/exe/diogenes

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/diogenes"
+
+exit(Diogenes::Cli.run(ARGV))

data/hk.pkl

@@ -0,0 +1,46 @@
+amends "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Builtins.pkl"
+
+fail_fast = false
+env {
+    ["HK_MISE"] = "1"
+}
+
+exclude =
+    List(
+        "vendor/**/*",
+        "tmp/**/*"
+    )
+
+local linters = new Mapping<String, Step> {
+    ["actionlint"] = Builtins.actionlint
+    ["mise"] = Builtins.mise
+    ["pkl"] = Builtins.pkl
+    ["yamlfmt"] = Builtins.yamlfmt
+    ["standard-rb"] = (Builtins.standard_rb) {
+        exclude = List("bin/*")
+        check = "bundle exec rake standard {{files}}"
+        fix = "bundle exec rake standard:fix {{ files }}"
+    }
+
+    // Generic linters
+    ["fix-smart-quotes"] = Builtins.fix_smart_quotes
+    ["mixed-line-ending"] = Builtins.mixed_line_ending
+	["newlines"] = Builtins.newlines
+	["trailing-whitespace"] = Builtins.trailing_whitespace
+}
+
+hooks {
+    ["pre-commit"] {
+        fix = true
+        stash = "git"
+        steps = linters
+    }
+    ["fix"] {
+        fix = true
+        steps = linters
+    }
+    ["check"] {
+        steps = linters
+    }
+}

data/lib/diogenes/cli/init.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "fileutils"
+
+module Diogenes
+  class Cli
+    class Init
+      DIOGENES_DIR = ".diogenes" #: String
+      TEMPLATES_ROOT = File.expand_path("../templates/init", __dir__) #: String
+
+      #: (cwd: String, out: IO, err: IO) -> Integer
+      def self.run(cwd:, out:, err:)
+        new(cwd: cwd, out: out, err: err).run
+      end
+
+      #: (cwd: String, out: IO, err: IO) -> void
+      def initialize(cwd:, out:, err:)
+        @cwd = cwd #: String
+        @out = out #: IO
+        @err = err #: IO
+      end
+
+      #: () -> Integer
+      def run
+        if diogenes_dir_exist?
+          @err.puts "Warning: #{DIOGENES_DIR}/ already exists — existing files will not be overwritten."
+        end
+
+        @out.puts "Initializing #{DIOGENES_DIR}/"
+
+        created = [] #: Array[String]
+        skipped = [] #: Array[String]
+
+        template_files.each do |relative_path|
+          destination = File.join(@cwd, DIOGENES_DIR, relative_path)
+
+          if File.exist?(destination)
+            skipped << relative_path
+            next
+          end
+
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(template_path(relative_path), destination)
+          created << relative_path
+        end
+
+        print_summary(created:, skipped:)
+        0
+      end
+
+      private
+
+      #: () -> bool
+      def diogenes_dir_exist?
+        Dir.exist?(File.join(@cwd, DIOGENES_DIR))
+      end
+
+      #: () -> Array[String]
+      def template_files
+        Dir.glob("**/*", base: TEMPLATES_ROOT, flags: File::FNM_DOTMATCH)
+          .reject { |path| path == "." || path.end_with?("/.") }
+          .select { |path| File.file?(template_path(path)) }
+          .sort
+      end
+
+      #: (String) -> String
+      def template_path(relative_path)
+        File.join(TEMPLATES_ROOT, relative_path)
+      end
+
+      #: (created: Array[String], skipped: Array[String]) -> void
+      def print_summary(created:, skipped:)
+        if created.any?
+          @out.puts "Initialized #{DIOGENES_DIR}/ with #{created.size} file#{"s" unless created.size == 1}."
+          created.each { |path| @out.puts "  created  #{DIOGENES_DIR}/#{path}" }
+        elsif skipped.any?
+          @out.puts "No files created — all #{skipped.size} template files already exist."
+        end
+
+        return if skipped.empty?
+
+        @out.puts "Skipped #{skipped.size} existing file#{"s" unless skipped.size == 1}:"
+        skipped.each { |path| @out.puts "  skipped  #{DIOGENES_DIR}/#{path}" }
+      end
+    end
+  end
+end

data/lib/diogenes/cli.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "cli/init"
+
+module Diogenes
+  class Cli
+    COMMANDS = {
+      "init" => Init
+    }.freeze #: Hash[String, Class]
+
+    #: (?Array[String] argv, ?out: IO, ?err: IO) -> Integer
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      new(argv: argv, out: out, err: err).run
+    end
+
+    #: (argv: Array[String], out: IO, err: IO) -> void
+    def initialize(argv:, out:, err:)
+      @argv = argv.dup #: Array[String]
+      @out = out #: IO
+      @err = err #: IO
+    end
+
+    #: () -> Integer
+    def run
+      command, *args = @argv
+
+      case command
+      when nil, "help", "-h", "--help"
+        print_help
+      when "version", "-v", "--version"
+        print_version
+      when *COMMANDS.keys
+        run_command(COMMANDS.fetch(command), args)
+      else
+        raise UserError, unknown_command_message(command)
+      end
+    rescue OptionParser::ParseError, UserError => e
+      @err.puts e.message
+      1
+    end
+
+    private
+
+    # Run a command
+    # --
+    #: (Class, Array[String]) -> Integer
+    def run_command(command_class, args)
+      raise UserError, "Unexpected arguments: #{args.join(" ")}" if args.any?
+
+      command_class.run(cwd: Dir.pwd, out: @out, err: @err)
+    end
+
+    #: () -> Integer
+    def print_help
+      @out.puts <<~HELP
+        Diogenes - The Ruby AI Feature Gatekeeper
+
+        Usage:
+          diogenes <command> [options]
+
+        Description:
+          Diogenes is a Ruby gem that holds your AI features to the same light. It has two jobs:
+          1. A five-gate gauntlet decision framework that determines whether something should be an AI feature in production, or whether it's a software problem in disguise. Derived from Ruby's core principles: least surprise, programmer happiness, and human-centered design.
+          2. An agent configuration build tool that lets you write your AI agent skills, rules, and hooks once in a canonical Ruby DSL, and Diogenes builds the right configuration for every agent you use: Claude Code, Cursor, Copilot, Codex, Gemini, and more.
+
+        Commands:
+          init      Initialize a new Diogenes project
+          build     Build the Diogenes agent configuration for a given target
+          evaluate  Evaluate a proposed AI feature through the five gates
+          validate  Validate the Diogenes agent configuration for a given target
+          help      Show help for a command
+          version   Show version information
+      HELP
+      0
+    end
+
+    #: () -> Integer
+    def print_version
+      @out.puts(Diogenes::VERSION)
+      0
+    end
+
+    # Print the unknown command message
+    # --
+    #: (String) -> String
+    def unknown_command_message(command)
+      <<~MESSAGE.strip
+        Unknown command: #{command}
+
+        Run `diogenes help` to see available commands.
+      MESSAGE
+    end
+  end
+end

data/lib/diogenes/templates/init/artifacts/decision_record.md.erb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+Diogenes.artifact "decision_record" do
+  description "Decision record produced by gate evaluation"
+  filename "<%= feature_slug %>_decision.md"
+
+  template <<~TEMPLATE
+    # AI Feature Decision Record
+
+    **Feature:** <%= feature_name %>
+    **Date:** <%= Date.today.strftime("%Y-%m-%d") %>
+    **Evaluator:** <%= evaluator %>
+    **Verdict:** <%= verdict %>
+
+    ---
+
+    ## Gate Results
+
+    | Gate | Principle | Result | Reason |
+    |------|-----------|--------|--------|
+    | 1. Failure Mode | Least surprise at scale | <%= gate_result(:failure_mode) %> | <%= gate_reason(:failure_mode) %> |
+    | 2. User Verifiable | Trust requires verification | <%= gate_result(:user_verifiable) %> | <%= gate_reason(:user_verifiable) %> |
+    | 3. Human in Loop | Human-centered, genuinely | <%= gate_result(:human_in_loop) %> | <%= gate_reason(:human_in_loop) %> |
+    | 4. Observability | Craftsmanship | <%= gate_result(:observability) %> | <%= gate_reason(:observability) %> |
+    | 5. Right Tool | Convention over configuration | <%= gate_result(:right_tool) %> | <%= gate_reason(:right_tool) %> |
+
+    ---
+
+    ## Verdict: <%= verdict %>
+
+    <% if verdict == "REJECT" || verdict == "PROCEED WITH CONDITIONS" %>
+    ## Recommended Alternative or Mitigation
+
+    <%= alternative %>
+    <% end %>
+
+    <% if verdict == "PROCEED" || verdict == "PROCEED WITH CONDITIONS" %>
+    ## Conditions for Proceeding
+
+    <%= conditions.empty? ? "None — all gates passed." : conditions %>
+    <% end %>
+
+    ---
+
+    ## Notes
+
+    <%= notes.empty? ? "_No additional notes._" : notes %>
+
+    ---
+
+    *Generated by [Diogenes](https://github.com/meaganewaller/diogenes)*
+  TEMPLATE
+end

data/lib/diogenes/templates/init/diogenes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Diogenes project configuration.
+# Run `diogenes build --all` after changing source files.
+
+Diogenes.configure do
+  name "My Project"
+  description "AI agent configuration for this project"
+
+  targets :claude_code, :cursor
+
+  artifacts_dir "docs/decisions"
+end

data/lib/diogenes/templates/init/hooks/README.md

@@ -0,0 +1,15 @@
+# Hooks
+
+Hooks define event-triggered behaviors that run automatically during agent sessions.
+
+Add `.rb` files to this directory when you're ready. Example:
+
+```ruby
+Diogenes.hook "run_tests_before_commit" do
+  trigger     "PreToolUse"
+  description "Remind the agent to run tests before committing"
+  prompt      <<~PROMPT
+    Before making any git commit, run the test suite and confirm it passes.
+  PROMPT
+end
+```

data/lib/diogenes/templates/init/rules/five_gates.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+Diogenes.rule "five_gates" do
+  description "The five Diogenes gates — default ruleset for AI feature decisions"
+
+  content <<~RULE
+    ## The Five Diogenes Gates
+
+    When evaluating or building AI features, apply these gates in order.
+    A gate failure is information, not a verdict — but it must be addressed
+    before shipping.
+
+    **Gate 1 — Failure Mode** (Least surprise at scale)
+    What happens when this feature is wrong? Recoverable failures pass.
+    Embarrassing failures pass with conditions. Catastrophic failures do not pass.
+
+    **Gate 2 — User Verifiable** (Trust requires verification)
+    Can the average user tell when the output is wrong? If the user lacks
+    domain expertise to evaluate AI output, the feature creates a confidence gap.
+
+    **Gate 3 — Human in the Loop** (Human-centered design, genuinely)
+    Is there a human with time, context, and authority to actually intervene?
+    Rubber-stamping is not a loop.
+
+    **Gate 4 — Observability** (Craftsmanship — you wouldn't ship blind)
+    Do you have monitoring to detect when this feature degrades in production?
+    Silent degradation is worse than no feature.
+
+    **Gate 5 — Right Tool** (Convention over configuration)
+    Is AI the right answer, or just the exciting one? Prefer the boring,
+    predictable software alternative when it serves the same need.
+  RULE
+end

data/lib/diogenes/templates/init/skills/example_skill.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Example skill demonstrating the full Diogenes skill DSL.
+# Copy this file, rename it, and customize the values for your project.
+
+Diogenes.skill "evaluate_feature" do
+  command "/evaluate-feature"
+  description "Walk a proposed AI feature through the five Diogenes gates"
+
+  prompt <<~PROMPT
+    You are helping a Ruby developer evaluate whether a proposed AI feature
+    should be built. Walk them through each of the five Diogenes gates in order,
+    asking focused questions and surfacing the failure mode clearly if a gate fails.
+
+    The feature being evaluated: {{input}}
+
+    The five gates are:
+    1. Failure Mode — What happens when this feature is wrong? Is the failure recoverable?
+    2. User Verifiable — Can the average user tell when it's wrong?
+    3. Human in the Loop — Is there a real human checking, with time and authority to intervene?
+    4. Observability — Do you have monitoring to know when it's going wrong in production?
+    5. Right Tool — Is AI the right answer, or just the exciting one?
+
+    For each gate:
+    - State the gate name and the Ruby principle it maps to
+    - Ask one focused question to determine pass or fail
+    - State the verdict clearly (PASS or FAIL)
+    - If FAIL: explain why and suggest what the right approach is instead
+
+    At the end, generate a structured decision record with a summary verdict:
+    PROCEED, REJECT, or PROCEED WITH CONDITIONS.
+  PROMPT
+end

data/lib/diogenes/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Diogenes
-  VERSION = "0.1.2"
+  VERSION = "0.1.3" #: String
 end

data/lib/diogenes.rb

@@ -1,8 +1,33 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
-require_relative "diogenes/version"
+require "zeitwerk"
+
+# Diogenes is the main module for the Diogenes gem.
+#
+# Provides configuration, CLI, and runtime library for the Diogenes gem.
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
 module Diogenes
+  # Base error class for Diogenes.
   class Error < StandardError; end
-  # Your code goes here...
+
+  # Raised when invalid arguments are passed to a method.
+  class ArgumentError < ::ArgumentError; end
+
+  # Raised when the configuration is invalid.
+  class ValidationError < Error; end
+
+  # Raised when the user provides invalid arguments to the CLI.
+  class UserError < Error; end
+
+  # Returns the version of the Diogenes gem.
+  #
+  # This is managed by the release-please workflow.
+  # --
+  #: () -> String
+  def self.version
+    VERSION
+  end
 end

data/sig/generated/diogenes/cli/init.rbs

@@ -0,0 +1,34 @@
+# Generated from lib/diogenes/cli/init.rb with RBS::Inline
+
+module Diogenes
+  class Cli
+    class Init
+      DIOGENES_DIR: String
+
+      TEMPLATES_ROOT: String
+
+      # : (cwd: String, out: IO, err: IO) -> Integer
+      def self.run: (cwd: String, out: IO, err: IO) -> Integer
+
+      # : (cwd: String, out: IO, err: IO) -> void
+      def initialize: (cwd: String, out: IO, err: IO) -> void
+
+      # : () -> Integer
+      def run: () -> Integer
+
+      private
+
+      # : () -> bool
+      def diogenes_dir_exist?: () -> bool
+
+      # : () -> Array[String]
+      def template_files: () -> Array[String]
+
+      # : (String) -> String
+      def template_path: (String) -> String
+
+      # : (created: Array[String], skipped: Array[String]) -> void
+      def print_summary: (created: Array[String], skipped: Array[String]) -> void
+    end
+  end
+end