ruact 0.0.6 → 0.0.8

data/spec/ruact/doctor_spec.rb

@@ -511,6 +511,141 @@ RSpec.describe Ruact::Doctor do
     end
   end
 
+  # --- JSON introspection (Story 15.3, FR107, AC1 + AC3 + AC4) ---
+
+  describe "#as_json (machine-readable report)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    context "when all checks pass" do
+      before do
+        make_manifest
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+      end
+
+      it "returns a document that round-trips through JSON.parse", :aggregate_failures do
+        report = doctor.as_json
+        reparsed = JSON.parse(JSON.generate(report))
+        expect(reparsed).to eq(report)
+      end
+
+      it "gates the document with the EXPERIMENTAL schema_version (0)" do
+        expect(doctor.as_json["schema_version"]).to eq(0)
+        expect(doctor.as_json["schema_version"]).to eq(Ruact::Doctor::SCHEMA_VERSION)
+      end
+
+      it "carries every check with name/status/message/remediation keys", :aggregate_failures do
+        checks = doctor.as_json["checks"]
+        expect(checks.map { |c| c["name"] }).to eq(described_class::CHECKS.map(&:to_s))
+        checks.each do |check|
+          expect(check.keys).to contain_exactly("name", "status", "message", "remediation")
+          expect(check["status"]).to be_a(String)
+          expect(check["message"]).to be_a(String)
+        end
+      end
+
+      it "reports top-level status 'pass' and exits-zero semantics" do
+        expect(doctor.as_json["status"]).to eq("pass")
+      end
+
+      it "emits NO prose to stdout (JSON mode is the document only)" do
+        expect { doctor.as_json }.not_to output.to_stdout
+      end
+    end
+
+    context "when a check fails" do
+      before do
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+        # manifest is missing → check_manifest fails
+      end
+
+      it "reports top-level status 'fail' (non-zero exit semantics)" do
+        expect(doctor.as_json["status"]).to eq("fail")
+      end
+
+      it "carries the separate machine-readable remediation for the failing check" do
+        manifest = doctor.as_json["checks"].find { |c| c["name"] == "manifest" }
+        expect(manifest["status"]).to eq("fail")
+        expect(manifest["remediation"]).to eq("Run vite build (or bin/dev) to generate the client manifest.")
+      end
+    end
+
+    context "when a check warns (Rack::Deflater mounted)" do
+      before do
+        make_manifest
+        make_controller(with_include: true)
+        make_layout(with_sentinel: true)
+        allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+        app = Struct.new(:middleware).new([Struct.new(:name).new("Rack::Deflater")])
+        allow(Rails).to receive(:application).and_return(app)
+      end
+
+      it "keeps status 'pass' — a :warn does not fail — but exposes the warn check" do
+        report = doctor.as_json
+        expect(report["status"]).to eq("pass")
+        flight = report["checks"].find { |c| c["name"] == "flight_middleware" }
+        expect(flight["status"]).to eq("warn")
+        expect(flight["remediation"]).to include("Exclude text/x-component from compression")
+      end
+    end
+
+    it "keeps the message byte-identical to the human tuple (remediation is separate)" do
+      _status, human_message = doctor.send(:check_manifest)
+      json_message = doctor.as_json["checks"].find { |c| c["name"] == "manifest" }["message"]
+      expect(json_message).to eq(human_message)
+    end
+  end
+
+  describe "#results / #passed? (shared compute, Story 15.3)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    before do
+      make_manifest
+      make_controller(with_include: true)
+      make_layout(with_sentinel: true)
+      allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+    end
+
+    it "returns one tuple per check, index-aligned with CHECKS" do
+      expect(doctor.results.length).to eq(described_class::CHECKS.length)
+    end
+
+    it "passed? is true when all checks pass/warn" do
+      expect(doctor.passed?).to be true
+    end
+
+    it "runs each check exactly once (as_json does not double-run check_vite's socket)" do
+      # check_vite opens a socket via TCPSocket.new; a single as_json must open it
+      # exactly once — proving #results is computed once, not per consumer.
+      doctor.as_json
+      expect(TCPSocket).to have_received(:new).once
+    end
+  end
+
+  describe "#run stays byte-identical after the #results refactor (Story 15.3, AC4a)", :story_15_3 do
+    subject(:doctor) { described_class.new }
+
+    before do
+      make_manifest
+      make_controller(with_include: true)
+      make_layout(with_sentinel: true)
+      allow(TCPSocket).to receive(:new).and_return(instance_double(TCPSocket, close: nil))
+    end
+
+    it "prints exactly the header + one format_result line per check (no JSON/prose leak), returns true" do
+      # Reconstruct the expected output from the SAME format_result the human
+      # path uses — proves #run still emits header + one glyph line per check
+      # (the optional 3rd remediation element is ignored) and nothing else.
+      lines = doctor.results.map { |status, message| doctor.send(:format_result, status, message) }.join("\n")
+      expected = "[ruact] Health check\n#{lines}\n"
+
+      expect { expect(doctor.run).to be true }.to output(expected).to_stdout
+    end
+  end
+
   describe "Rake task definition (Story 5.12)", :story_5_12 do
     # Loads gem/lib/tasks/ruact.rake into a fresh Rake::Application so the
     # task table is isolated from any other spec that may have loaded tasks.
@@ -549,5 +684,11 @@ RSpec.describe Ruact::Doctor do
       # actions is a list of Procs; just assert at least one is attached
       expect(task.actions).not_to be_empty
     end
+
+    it "defines Rake::Task['ruact:routes'] with an action (Story 15.3)", :story_15_3 do
+      task = rake_app.lookup("ruact:routes")
+      expect(task).not_to be_nil
+      expect(task.actions).not_to be_empty
+    end
   end
 end

data/spec/ruact/erb_preprocessor_spec.rb

@@ -116,6 +116,151 @@ module Ruact
       end
     end
 
+    # Story 15.2 (FR106) — children inside a PascalCase component tag (a matching
+    # closing tag) fail LOUDLY at preprocess time instead of degrading silently.
+    describe "loud children error (FR106)", :story_15_2 do
+      def run(source, identifier: nil)
+        described_class.transform(source, identifier: identifier)
+      end
+
+      it "raises on `<Card>Hello</Card>` naming component + fix (AC#1)" do
+        expect { run("<Card>Hello</Card>") }
+          .to raise_error(ChildrenNotSupportedError) do |e|
+            expect(e.message).to include("Card")
+            expect(e.message).to include("children are not supported")
+            expect(e.message).to include("pass content as a prop")
+            expect(e.message).to include("<Card content={...} />")
+          end
+      end
+
+      it "is a Ruact::PreprocessorError (AC#1 — subclass IS-A base)" do
+        expect { run("<Card>Hello</Card>") }.to raise_error(Ruact::PreprocessorError)
+      end
+
+      it "raises on an empty pair `<Card></Card>` (AC#1)" do
+        expect { run("<Card></Card>") }.to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      it "raises on multi-line children (AC#1)" do
+        source = "<Card>\n  <p>hi</p>\n</Card>"
+        expect { run(source) }.to raise_error(ChildrenNotSupportedError, /children are not supported/)
+      end
+
+      it "raises on a paired tag that also holds a nested component" do
+        expect { run("<Card><Button /></Card>") }
+          .to raise_error(ChildrenNotSupportedError, /<Card>/)
+      end
+
+      it "names the supplied identifier and the correct line for a non-first-line pair (AC#4)" do
+        source = "line1\nline2\n<Card>Hello</Card>"
+        expect { run(source, identifier: "app/views/posts/show.html.erb") }
+          .to raise_error(ChildrenNotSupportedError) do |e|
+            expect(e.message).to include("app/views/posts/show.html.erb:3")
+          end
+      end
+
+      it "reports the opening tag's line, honoring attributes on the opening tag" do
+        expect { run("<Card variant={:wide}>x</Card>", identifier: "t.erb") }
+          .to raise_error(ChildrenNotSupportedError, /t\.erb:1/)
+      end
+
+      # Regression (Codex Round 1, Patch 1): a MULTI-LINE Suspense opening tag
+      # must not shift the reported line — the `<Card>` below is physically on
+      # line 5 and must report :5 (Suspense is masked newline-for-newline).
+      it "reports the exact source line even after a multi-line Suspense opening" do
+        source = <<~ERB
+          <Suspense
+            fallback="loading"
+            delay="2.5">
+          </Suspense>
+          <Card>Hello</Card>
+        ERB
+        expect { run(source, identifier: "t.erb") }
+          .to raise_error(ChildrenNotSupportedError, /t\.erb:5/)
+      end
+
+      # Regression (Codex Round 2, Patch 1): a `</Dialog>` living inside an ERB
+      # island (Ruby string/comment) must NOT be mistaken for a real component
+      # closing tag — a valid bare `<Dialog open={true}>` stays valid.
+      it "does not false-pair a bare opening with a `</Tag>` inside an ERB island" do
+        source = %(<Dialog open={true}>\n<% x = "</Dialog>" %>)
+        expect { run(source) }.not_to raise_error
+      end
+
+      it "still fires when the closing tag is real ERB body, not inside `<% %>`" do
+        expect { run("<Card><%= @body %></Card>") }
+          .to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      # Regression (Codex Round 2, Patch 2): many bare non-self-closing openings
+      # with no close must stay linear (single-pass stack scan) and silent (D3).
+      it "stays silent and does not blow up on many bare unclosed openings" do
+        source = "<Dialog open={true}>\n" * 5000
+        expect { run(source) }.not_to raise_error
+      end
+
+      # Regression (Codex Round 3, Patch 1): stray/unmatched PascalCase closing
+      # tags (no preceding matching open) are literal text — never an error — and
+      # must stay linear (per-name O(1) lookup, no `rindex`). Correctness pin;
+      # perf verified live, not timed here (avoids a flaky benchmark spec).
+      it "does not raise on stray closing tags with no matching opening" do
+        source = "</Card>\n" * 5000
+        expect { run(source) }.not_to raise_error
+      end
+
+      it "still raises when a real opening precedes the stray closes" do
+        source = "<Card>x</Card>\n#{'</Card>' * 100}"
+        expect { run(source) }.to raise_error(ChildrenNotSupportedError, /Card/)
+      end
+
+      # AC#2 regression — the loud error must NOT fire on any valid pattern.
+      describe "does NOT fire on valid patterns (AC#2 byte-identical)" do
+        it "self-closing tag, no props" do
+          expect { run("<Button />") }.not_to raise_error
+        end
+
+        it "self-closing tag with props" do
+          expect { run("<LikeButton postId={@post.id} />") }.not_to raise_error
+        end
+
+        it "bare non-self-closing opening tag with NO closing tag (`<Dialog open={true}>`)" do
+          expect { run("<Dialog open={true}>") }.not_to raise_error
+        end
+
+        it "nested-brace prop value" do
+          expect { run("<Select options={Category.all.map { |c| c.id }} />") }.not_to raise_error
+        end
+
+        it "multiple self-closing components" do
+          expect { run('<Button /> and <Badge label={"hello"} />') }.not_to raise_error
+        end
+
+        it "mixed HTML around a self-closing component" do
+          source = %(<div class="container">\n  <h1>Hi</h1>\n  <LikeButton postId={1} />\n</div>)
+          expect { run(source) }.not_to raise_error
+        end
+
+        it "emits byte-identical output for `<Dialog open={true}>`" do
+          expect(run("<Dialog open={true}>"))
+            .to eq(%(<%= __ruact_component__("Dialog", { "open" => true }) %>))
+        end
+      end
+
+      # AC#3 — Suspense children are the ONE legitimate paired PascalCase tag and
+      # must never trip the error (normalized to <ruact-suspense> in Step 1).
+      describe "Suspense children never trip the error (AC#3)" do
+        it "does not raise for `<Suspense><Spinner /></Suspense>`" do
+          expect { run(%(<Suspense fallback="loading"><Spinner /></Suspense>)) }.not_to raise_error
+        end
+
+        it "normalizes Suspense to <ruact-suspense> exactly as today" do
+          result = run(%(<Suspense fallback="loading"><Spinner /></Suspense>))
+          expect(result).to include(%(data-ruact-fallback="loading"))
+          expect(result).to include("</ruact-suspense>")
+        end
+      end
+    end
+
     # Story 13.5 (FR100) — preprocess-time component-contract validation, wired
     # through an injectable registry seam (a stub responding to +contract_for+).
     describe "component contract validation", :story_13_5 do

data/spec/ruact/install_generator_spec.rb

@@ -359,6 +359,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
             gen.create_server_functions_directory
             gen.append_gitignore_entries
             gen.create_vite_config
+            gen.create_agents_md
           end.not_to raise_error
         end
 
@@ -371,6 +372,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
         expect(File.read(File.join(app_root, ".gitignore")))
           .to include("app/javascript/.ruact/server-functions.ts")
         expect(File).to exist(File.join(app_root, "vite.config.js"))
+        expect(File).to exist(File.join(app_root, "AGENTS.md"))
       end
     end
   end
@@ -889,4 +891,287 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       end
     end
   end
+
+  # Story 15.1 (FR105) — `ruact:install` emits an AGENTS.md teaching coding
+  # agents the ruact conventions, traps, and verification commands. The ruact
+  # content is delimited by explicit markers so re-runs are idempotent, a
+  # user-authored AGENTS.md is appended to (never clobbered), and --force
+  # refreshes ONLY the marked section. Content assertions grep stable tokens
+  # (commands, file paths, API names) — never full-file snapshots, since later
+  # stories (15.2/15.3/15.4) deliberately evolve the prose.
+  describe "install generator — AGENTS.md emission (Story 15.1 — FR105)", :story_15_1 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+
+    let(:app_root) { Dir.mktmpdir("ruact_install_1501") }
+    let(:agents_md_path) { File.join(app_root, "AGENTS.md") }
+    let(:begin_marker) { "<!-- ruact:begin -->" }
+    let(:end_marker) { "<!-- ruact:end -->" }
+    let(:template_path) do
+      File.expand_path("../../lib/generators/ruact/install/templates/AGENTS.md.tt", __dir__)
+    end
+
+    after { FileUtils.rm_rf(app_root) }
+
+    def build_generator(root, opts = {})
+      Ruact::Generators::InstallGenerator.new([], opts, destination_root: root)
+    end
+
+    def silently
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    ensure
+      $stdout = original
+    end
+
+    # Captures and returns the generator's say/say_status stdout for text asserts.
+    def capture_stdout
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+      $stdout.string
+    ensure
+      $stdout = original
+    end
+
+    describe "fresh emission (AC#1)" do
+      it "creates AGENTS.md delimited by the ruact markers", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File).to exist(agents_md_path)
+        content = File.read(agents_md_path)
+        expect(content).to start_with(begin_marker)
+        expect(content.rstrip).to end_with(end_marker)
+      end
+
+      it "covers the model, codegen, queries and verification areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # The verb rule (mutations = non-GET routed actions on Ruact::Server)
+        expect(content).to include("Ruact::Server")
+        expect(content).to include("non-GET")
+        # Route-driven codegen: ground-truth file + regenerate command
+        expect(content).to include("app/javascript/.ruact/server-functions.ts")
+        expect(content).to include("bin/rails ruact:server_functions:generate")
+        # Queries (reads)
+        expect(content).to include("Ruact::Query")
+        expect(content).to include("app/queries/")
+        expect(content).to include("ruact_queries")
+        expect(content).to include("useQuery")
+        # Verification commands (the only two that exist today)
+        expect(content).to include("bin/rails ruact:doctor")
+        # Docs pointers
+        expect(content).to include("https://ruact.dev")
+        expect(content).to include("llms.txt")
+      end
+
+      it "covers the five traps and the safety areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # Trap 1 — children unsupported / self-closing only
+        expect(content).to include("self-closing")
+        expect(content).to include("children")
+        # Trap 2 — Ruby (not JS) inside {} props
+        expect(content).to include("Ruby, not JavaScript")
+        # Trap 3 — Accept-header dual shape (exact application/json)
+        expect(content).to include("Accept")
+        expect(content).to include("application/json")
+        # Trap 4 — ruact_errors fall-through
+        expect(content).to include("ruact_errors")
+        expect(content).to include("fall-through")
+        # Trap 5 — name derivation from routes
+        expect(content).to include("createPost")
+        expect(content).to include("ruact_function_name")
+        # Serialization allowlist
+        expect(content).to include("ruact_props")
+        expect(content).to include("strict_serialization")
+        # SGID helpers (purpose + expiry required grain)
+        expect(content).to include("Ruact.signed_global_id")
+        expect(content).to include("Ruact.locate_signed")
+      end
+
+      it "makes no claim before its artifact (AC#4 — content honesty)", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # (The loud children `PreprocessorError` is Story 15.2's shipped
+        # artifact, and the `--json` introspection commands are Story 15.3's —
+        # both may now be claimed; see the `:story_15_2` / `:story_15_3` guards
+        # below that PIN each claim's presence. Story 15.4's public render
+        # helpers are now shipped too — see the `:story_15_4` guard below.)
+        #
+        # tsc does not run in a fresh install (no typescript devDep / tsconfig) —
+        # it may only appear conditionally phrased (D1).
+        expect(content).to match(/if your app has typescript tooling/i) if content.include?("tsc")
+        # Volatile strings must not be quoted: no gem version pins.
+        expect(content).not_to match(/\b0\.0\.\d+\b/)
+      end
+
+      # Story 15.2 (D2) — now that the loud children error is a shipped artifact,
+      # trap #1 truthfully claims it fails LOUDLY (was "fails silently" in 15.1).
+      it "trap #1 claims the loud PreprocessorError (Story 15.2 D2)", :aggregate_failures, :story_15_2 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include("PreprocessorError")
+        expect(content).to match(/fail LOUDLY/i)
+        expect(content).not_to match(/fail silently/i)
+      end
+
+      # Story 15.3 (D2) — now that the `--json` introspection surface is a shipped
+      # artifact, the "Verify your work" section references it (relaxes the 15.1
+      # honesty guard above). This PINS the claim AND its EXPERIMENTAL framing so
+      # the template never presents the JSON shape as a stable contract.
+      it "references --json introspection as EXPERIMENTAL (15.3 D2)", :aggregate_failures, :story_15_3 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include("ruact:routes -- --json")
+        expect(content).to include("ruact:doctor")
+        expect(content).to include("Append `-- --json`")
+        expect(content).to match(/EXPERIMENTAL/)
+        expect(content).to include("schema_version")
+      end
+
+      # Story 15.4 (D6) — now that the public render-assertion helpers are a
+      # shipped artifact (FR108), the "Verify your work" section references them.
+      # This PINS the claim (name + explicit require + the JSON-vs-Flight rule)
+      # so it stays consistent with `website/public/llms.txt`.
+      it "references the ruact/testing render helpers (15.4 D6)", :aggregate_failures, :story_15_4 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include(%(require "ruact/testing"))
+        expect(content).to include("have_ruact_component")
+        expect(content).to include("JSON.parse(response.body)")
+      end
+    end
+
+    describe "idempotency (AC#2 — double-run zero diff)" do
+      it "leaves the file byte-identical on a second run and reports a skip", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        first = File.read(agents_md_path)
+
+        output = capture_stdout { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path)).to eq(first)
+        expect(output).to include("skip")
+      end
+    end
+
+    describe "append mode (AC#2 — user-authored AGENTS.md)" do
+      let(:user_content) { "# My app\n\nUse pnpm here. Never touch config/secrets.yml.\n" }
+
+      it "appends the marked section preserving every pre-existing user byte", :aggregate_failures do
+        File.write(agents_md_path, user_content)
+
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to start_with(user_content)
+        expect(content.scan(begin_marker).count).to eq(1)
+        expect(content.scan(end_marker).count).to eq(1)
+        expect(content).to include("\n\n#{begin_marker}")
+      end
+
+      it "blank-line separates the section when the user file lacks a trailing newline" do
+        File.write(agents_md_path, "# My app — no trailing newline")
+
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path))
+          .to include("# My app — no trailing newline\n\n#{begin_marker}")
+      end
+
+      it "appending then re-running is idempotent (skip, zero diff)" do
+        File.write(agents_md_path, user_content)
+        silently { build_generator(app_root).create_agents_md }
+        appended = File.read(agents_md_path)
+
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path)).to eq(appended)
+      end
+    end
+
+    describe "--force refresh (AC#2 — marked-block-only)" do
+      it "replaces ONLY the between-marker content, never user bytes outside", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        section = File.read(agents_md_path)
+        stale = section.sub("## Five traps", "## STALE CONTENT FROM AN OLDER GEM")
+        File.write(agents_md_path, "# mine, above\n\n#{stale}\n# mine, below\n")
+
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to start_with("# mine, above\n")
+        expect(content).to end_with("# mine, below\n")
+        expect(content).to include("## Five traps")
+        expect(content).not_to include("STALE CONTENT FROM AN OLDER GEM")
+        expect(content.scan(begin_marker).count).to eq(1)
+      end
+
+      it "creates the file under --force when none exists" do
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        expect(File.read(agents_md_path)).to include(begin_marker)
+      end
+    end
+
+    # Codex R1 — an incomplete marker state is ambiguous in BOTH directions
+    # (appending would duplicate content next to a stray marker; replacing
+    # would guess the range), so the only byte-safe move is warn + no-op.
+    describe "broken marker pair (byte-safety)" do
+      [
+        ["a begin marker without its end marker",
+         "# mine\n\n<!-- ruact:begin -->\ntruncated ruact section, no end marker\n"],
+        ["an end marker without its begin marker",
+         "# mine\n\nstray tail of a ruact section\n<!-- ruact:end -->\n"],
+        ["an end marker preceding the begin marker",
+         "# mine\n\n<!-- ruact:end -->\nreversed\n<!-- ruact:begin -->\n"],
+        # Codex R2 — a VALID pair plus stray extra markers is still ambiguous:
+        # skip/refresh would leave (or eat past) the unmatched marker.
+        ["a stray end marker before a valid pair",
+         "<!-- ruact:end -->\nstray\n\n<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n"],
+        ["a stray begin marker after a valid pair",
+         "<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n\nstray\n<!-- ruact:begin -->\n"],
+        ["two complete marker pairs",
+         "<!-- ruact:begin -->\none\n<!-- ruact:end -->\n\n<!-- ruact:begin -->\ntwo\n<!-- ruact:end -->\n"]
+      ].each do |(label, broken)|
+        it "warns and leaves the file untouched with #{label} (no --force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+
+          output = capture_stdout { build_generator(app_root).create_agents_md }
+
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+
+        it "warns and leaves the file untouched with #{label} (--force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+
+          output = capture_stdout { build_generator(app_root, { force: true }).create_agents_md }
+
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+      end
+    end
+
+    describe "action ordering + template budget" do
+      it "defines create_agents_md BEFORE install_javascript_dependencies" do
+        klass = Ruact::Generators::InstallGenerator
+        line = ->(name) { klass.instance_method(name).source_location.last }
+        expect(line.call(:create_agents_md)).to be < line.call(:install_javascript_dependencies)
+      end
+
+      # AC#3 tripwire — the ~150-line budget is the epic's scope probe; the
+      # tripwire's tolerance is 160 (the tripwire's, not the product contract's).
+      it "keeps the template body at or under 160 lines" do
+        expect(File.read(template_path).lines.count).to be <= 160
+      end
+    end
+  end
 end