agentilda 1.0.3

data/lib/agentilda/diagram.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # `agentilda states` — the state machine as a terminal picture.
+  #
+  # {Documentation} already renders this machine as a Markdown table and a
+  # mermaid block, for a browser. This is the same machine, walked the same
+  # way, shaped for a terminal instead: unicode arrows, no browser required.
+  #
+  # Every section below is read off {StateMachine} and {STATUSES} rather than
+  # drawn by hand, for the reason {Documentation} gives for doing the same
+  # thing: three hand-maintained pictures of this machine have already
+  # drifted apart once, and a fourth is not the fix.
+  class Diagram
+    include UI
+
+    # Drawn between two states on the same line.
+    ARROW = "──▶"
+
+    # @return [String] the whole diagram, newline-terminated
+    def render
+      [
+        heading,
+        spine_section,
+        rejoin_section,
+        other_section,
+        terminal_section,
+        family_section
+      ].compact.join("\n\n") + "\n"
+    end
+
+    private
+
+    # @return [String]
+    def heading
+      paint("Spec → Plan → Build — the state machine", :bold) + "\n" +
+        paint("(derived from lib/agentilda/state_machine.rb — `agentilda docs` for the Markdown form)",
+          :bright_black)
+    end
+
+    # The path a bare `promote!` walks: {StateMachine::SPINE}, followed from
+    # `:new` until a state has no entry left to follow.
+    #
+    # @return [String]
+    def spine_section
+      section("MAIN SPINE", "a bare `promote` walks this path",
+        ["  " + spine_chain.map { |key| node(key) }.join(" #{ARROW} ")])
+    end
+
+    # {StateMachine::SPINE} entries whose source never appears on the walk
+    # above — states that sit off the spine but whose default `promote!`
+    # rejoins it, e.g. a rejected pull request resubmitted for review.
+    #
+    # @return [String, nil]
+    def rejoin_section
+      rows = StateMachine::SPINE
+        .except(*spine_chain)
+        .map { |from, to| "  #{node(from)} #{ARROW} #{node(to)}" }
+
+      section("REJOINING THE SPINE", "off-spine states whose default promotion lands back on it", rows)
+    end
+
+    # Everything {StateMachine} allows that the two sections above do not
+    # already draw: blocking, deferring, discarding, review outcomes,
+    # rollback — read off {StateMachine.outbound} state by state, in
+    # {STATUSES} order, so nothing the machine permits is left undrawn.
+    #
+    # @return [String, nil]
+    def other_section
+      drawn = StateMachine::SPINE.to_a
+
+      groups = STATUSES.filter_map { |s|
+        targets = StateMachine.outbound(s.key).reject { |to| drawn.include?([s.key, to]) }
+        [s.key, targets] unless targets.empty?
+      }
+
+      section("OTHER TRANSITIONS", "everything else the machine permits", groups.flat_map { |key, targets|
+        fan_out(key, targets)
+      })
+    end
+
+    # @return [String, nil]
+    def terminal_section
+      rows = STATUSES.select(&:terminal?).map { |s| "  #{node(s.key)}" }
+      section("TERMINAL", "nothing follows these", rows)
+    end
+
+    # {StateMachine::FAMILIES} share an invariant on purpose, and a folder's
+    # contents alone cannot tell their members apart — worth saying next to a
+    # diagram, or the members read like an oversight rather than a rule.
+    #
+    # @return [String, nil]
+    def family_section
+      rows = StateMachine::FAMILIES.map { |members| "  #{members.map { |key| node(key) }.join(" / ")}" }
+
+      section("LOOK-ALIKE FAMILIES", "same contents on disk; only the folder name tells them apart", rows)
+    end
+
+    # `:new`, followed through {StateMachine::SPINE} until nothing follows.
+    #
+    # @return [Array<Symbol>]
+    def spine_chain
+      @spine_chain ||= [].tap { |chain|
+        key = :new
+        while key
+          chain << key
+          key = StateMachine::SPINE[key]
+        end
+      }
+    end
+
+    # One state and its outbound arrows, drawn as a small tree so several
+    # targets from one source read as a fan-out rather than as unrelated
+    # lines that happen to repeat the source.
+    #
+    # @param key [Symbol]
+    # @param targets [Array<Symbol>]
+    # @return [Array<String>]
+    def fan_out(key, targets)
+      lines = targets.each_with_index.map { |to, i|
+        connector = (i == targets.size - 1) ? "└─▶" : "├─▶"
+        "      #{connector} #{node(to)}"
+      }
+      ["  #{node(key)}", *lines]
+    end
+
+    # @param key [Symbol]
+    # @return [String]
+    def node(key)
+      status = STATUS_BY_KEY.fetch(key)
+      paint("#{status.emoji} #{status.label}", :bold)
+    end
+
+    # @param title [String]
+    # @param subtitle [String]
+    # @param rows [Array<String>]
+    # @return [String, nil] nil when there is nothing to show, so {#render} can drop it
+    def section(title, subtitle, rows)
+      return nil if rows.empty?
+
+      "#{paint(title, :bold)}  #{paint("(#{subtitle})", :bright_black)}\n\n#{rows.join("\n")}"
+    end
+  end
+end

data/lib/agentilda/documentation.rb

@@ -0,0 +1,429 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Generates the conventions document from the state machine itself.
+  #
+  # The tables and the diagram are DERIVED — from {STATUSES}, {StateMachine.inbound}
+  # and {Ordinal} — so they cannot drift from the tool the way three
+  # hand-maintained copies of the status table already did.
+  #
+  # The prose is not derived, because a machine cannot invent the reasoning: why
+  # the tool refuses rather than guesses, why a retroactive plan gets its own
+  # number shape, what happens to this scheme if a real issue tracker arrives.
+  # That lives in the heredocs below, in one place, and is emitted alongside the
+  # generated parts.
+  class Documentation
+    # @return [String] the whole document
+    def render
+      [
+        header,
+        numbering,
+        starting,
+        status_table,
+        blocking,
+        transitions,
+        diagram,
+        files_section,
+        pull_requests,
+        footer
+      ].join("\n")
+    end
+
+    private
+
+    # @return [String]
+    def header
+      <<~MARKDOWN
+        # Spec → Plan → Build
+
+        > [!IMPORTANT]
+        > **This file is auto generated.**
+        >
+        > To regenerate it, run `agentilda docs` (which by the default
+        > writes to ${HOME}/.agents/context/workflow.md`). To override
+        > the destination, use the -o | --output <file> option.
+        >
+        > After changing the state machine. Editing it by hand puts it back into the
+        > condition it was written to end: three copies of the same table, quietly
+        > disagreeing.
+
+        Every project keeps its plans in a `#{Agentilda::PLANS_DIR}/` directory at its root.
+        Each medium-to-large feature gets one folder, and the folder's **name is its
+        state**: the number identifies it forever, the emoji says what phase it is in,
+        and the slug says what it is.
+
+        There are three phases, and each one has a file that proves it happened:
+
+        | Phase | State | The file that proves it |
+        | :---- | :---- | :---------------------- |
+        | **spec** | #{status(:new).emoji} #{status(:new).label} | `spec.md` |
+        | **plan** | #{status(:planned).emoji} #{status(:planned).label} | `plan.md` |
+        | **build** | #{status(:building).emoji} → #{status(:ready_for_review).emoji} → #{status(:in_review).emoji} → #{status(:approved).emoji} | `pull-requests.md` |
+
+        Those files are not paperwork. They are what the tool checks: a folder may not
+        claim a phase whose file is missing, and `agentilda resync dirs` renames
+        any folder whose emoji its contents do not support.
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def numbering
+      <<~MARKDOWN
+        ## The number
+
+        A plan's number is its identity. It is set once, when the folder is created,
+        and never changes: branch names, pull request titles and every
+        `pull-requests.md` join on it, and renumbering breaks all of them silently.
+
+        The shape is always `NNN.MM`:
+
+        ```
+        #{Agentilda::PLANS_DIR}/000.00-#{status(:new).emoji}-initial-spec
+        #{Agentilda::PLANS_DIR}/001.00-#{status(:approved).emoji}-dev-foundation
+        #{Agentilda::PLANS_DIR}/001.01-#{status(:approved).emoji}-schedule-k1-backfill   <- shipped between 001 and 002,
+        #{Agentilda::PLANS_DIR}/002.00-#{status(:planned).emoji}-tenancy-households        specified afterwards
+        ```
+
+        - **`NNN` counts from `000`.** The first plan of a project is `000.00`; after
+          that it is the highest major plus one, zero-padded to three digits.
+        - **`MM` is `00` for an ordinary plan** — one specified before it was built.
+        - **`MM` from `01` to `99` marks a retroactive plan**: work that shipped with no
+          specification, documented after the fact. `agentilda create --after 001`
+          takes the next free slot in the gap after 001.
+
+        `001.01` is a **sibling of 001 that arrived later, not a part of 001**. The dot
+        reads as containment in almost every other numbering scheme, and here it does
+        not — which is worth saying wherever the scheme is described, because the
+        containment reading is the one a new reader brings.
+
+        Two digits, always. One would sort into the middle of the two-digit range —
+        `001.09` < `001.1` < `001.10` — so a single mixed-width folder silently
+        reorders the index. Two digits also retire the question of running out: 99
+        slots per gap, against a gap that closes the moment the next plan is created.
+
+        > [!NOTE]
+        > Padding every plan to `NNN.MM` is a deliberate choice, and it costs something.
+        > A bare `018` next to `018.01` would have told you at a glance which plan was
+        > specified in advance and which was written afterwards. With uniform padding
+        > that distinction is no longer readable from the number alone — it is carried
+        > by `MM > 0`, which you have to know to look for. What padding buys is
+        > alignment and one shape to parse everywhere.
+
+        **A retroactive `spec.md` must open with a dated line saying so**, naming the
+        pull requests it describes. It documents what exists; it does not pretend to
+        have decided anything in advance. Anchor by *when the work merged*, not by what
+        it is about — compare merge dates against folder creation dates
+        (`git log --diff-filter=A`). Anchoring by topic invites an argument nobody can
+        settle, and the number is a slot, not a claim about subject matter.
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def starting
+      headings = Agentilda::Brief::HEADINGS.map { |h| "- `## #{h}`" }.join("\n")
+
+      <<~MARKDOWN
+        ## Starting a feature that does not exist yet
+
+        `agentilda create <two to five words>` mints the folder at #{status(:new).emoji} #{status(:new).label}
+        and, for a genuinely new feature, scaffolds `spec.md` with a title and four
+        headings, verbatim:
+
+        #{headings}
+
+        `#{Agentilda::Brief::AGENT_NAME}` — a half-agent: it runs only inside `create` and
+        holds no roster entry — then makes a best-effort attempt at each from what
+        the project already has on disk — its own docs, `#{Agentilda::Brief::BACKLOG_FILE}` when
+        the project keeps one, anything already downloaded or already built that
+        bears on the topic — and opens the result for a human to finish.
+        `--no-draft` skips the attempt and leaves the headings bare; `--no-open`
+        leaves the file for you to open.
+
+        **Nothing else belongs in that first pass.** It writes no `## Goals`, no
+        `## Non-Goals`, no conclusions — deciding those before `leah-researcher` and
+        `yoda-writer` have looked is choosing the answer before the research runs.
+        Above all, it writes no heading beginning with the word "Research": that
+        heading is not decoration, it is the #{status(:researched).emoji} #{status(:researched).label} invariant, so writing
+        one — even empty — flips the folder's state out from under whoever reads it
+        next, and the research nobody did gets skipped rather than assigned.
+
+        This is only for work that does not exist yet. `create --after <plan> --prs
+        <n,...>` is the other path — the work already shipped, so `yoda-writer`
+        reconstructs the specification from the pull requests instead of guessing at
+        a feature that has no facts yet to guess from.
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def status_table
+      rows = Agentilda::STATUSES.map do |s|
+        required = s.requires.empty? ? "—" : s.requires.map { |f| "`#{f}`" }.join(", ")
+        "| #{s.emoji} | **#{s.label}** | `#{s.key}` | #{required} | #{s.note} |"
+      end
+
+      <<~MARKDOWN
+        ## The states
+
+        | Symbol | Meaning | Key | Files required | Description |
+        | :----: | :------ | :-- | :------------- | :---------- |
+        #{rows.join("\n")}
+
+        "Files required" is a **minimum**, not an exact match: a #{status(:new).emoji} folder that
+        has grown a `plan.md` still satisfies #{status(:new).emoji}, and is #{status(:planned).emoji} anyway. That is
+        why `resync dirs` moves a folder to the furthest state its contents justify
+        rather than only fixing outright lies.
+
+        Some states share their requirements on purpose, and are told apart only by the
+        folder name. #{status(:blocked).emoji} #{status(:blocked).label} and #{status(:product_blocked).emoji} #{status(:product_blocked).label} both mean "a human must
+        decide before this can move"; *which* human is recorded nowhere but the emoji.
+        #{StateMachine::FAMILIES.last.map { |k| status(k).emoji }.join(" ")} all mean "the work exists and pull requests are open"; whether
+        anyone has started reviewing is written down nowhere either.
+
+        So nothing re-derives one of them from a folder's contents — otherwise every
+        #{status(:blocked).emoji} would silently become #{status(:product_blocked).emoji} the first time anything resynced. A folder
+        falling back into that group from outside lands on its weakest member,
+        #{status(StateMachine::FAMILIES.last.first).emoji} #{status(StateMachine::FAMILIES.last.first).label}, because that is all its contents can prove.
+
+        #{merged_note}
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def merged_note
+      "🟣 Merged is deliberately **not** a folder state. It describes a pull request, " \
+      "and a folder that claimed it would be claiming a pull request's condition as its own."
+    end
+
+    # Why this is prose rather than another derived table: the mechanism is a
+    # rule about the *contents* of one file, and the only part of it a program
+    # can see is the invariant. Everything that makes the rule safe — a human
+    # types the command, an agent never answers anything — is a decision, and
+    # decisions belong in sentences.
+    #
+    # @return [String]
+    def blocking
+      settled = StateMachine::SETTLED.map { |k| status(k).emoji }.join(" ")
+
+      <<~MARKDOWN
+        ## When a plan is stopped, and how it starts again
+
+        #{status(:blocked).emoji} #{status(:blocked).label} and #{status(:product_blocked).emoji} #{status(:product_blocked).label} mean an agent hit a question that was not
+        its to answer and wrote `blocked.md` instead of guessing past it. Both belong to
+        the settled group `agentilda run` leaves alone (#{settled}), so the loop
+        never offers a stopped plan to anybody. A loop that could move one would make
+        the state mean nothing.
+
+        Questions are numbered `B1`, `B2`, and that numbering is how the file gets
+        referenced in conversation and in pull requests. **`blocked.md` holds open
+        questions and nothing else.** That is what the #{status(:blocked).emoji}/#{status(:product_blocked).emoji} invariant reads, so a
+        file naming no question justifies neither state and `resync dirs` renames the
+        folder out of it.
+
+        Which is how a block drains, in pieces:
+
+        1. A human writes each answer under `## Answers` as it arrives, dated and
+           attributed to whoever decided.
+        1. `agentilda unblock NNN --commit` hands the folder to `lando-broker`.
+           Nothing else reaches it: answers arriving is not a fact the tool can
+           observe, so a human running the command *is* the signal.
+        1. `lando-broker` folds each answered question into the document that question
+           was stopping — `spec.md` when the answer changes what we are building or
+           why, `plan.md` when it changes how or in what order — and deletes the
+           question and its answer from `blocked.md`.
+        1. When the last question goes, the file goes with it, and the folder leaves
+           #{status(:blocked).emoji} on the resync that follows.
+
+        An entry that names no decider, carries no date, or restates the options
+        instead of choosing one is not an answer, and is left exactly where it is.
+        So is any question nobody has answered yet: two answers out of five is a
+        successful run, and the plan stays stopped on the other three, which is true.
+        `lando-broker` never answers a question itself, and never retires one for
+        being stale — dropping a question is a human's call, and it makes the plan
+        #{status(:deferred).emoji} #{status(:deferred).label} or #{status(:discarded).emoji} #{status(:discarded).label}, not quietly shorter.
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def transitions
+      rows = Agentilda::STATUSES.map do |s|
+        out = StateMachine.outbound(s.key)
+        targets = out.empty? ? "_terminal_" : out.map { |k| status(k).emoji }.join(" ")
+        spine = StateMachine::SPINE[s.key]
+        "| #{s.emoji} #{s.label} | #{targets} | #{spine ? "#{status(spine).emoji} #{status(spine).label}" : "—"} |"
+      end
+
+      <<~MARKDOWN
+        ## Transitions
+
+        | From | May become | `promote` goes to |
+        | :--- | :--------- | :---------------- |
+        #{rows.join("\n")}
+
+        A bare promote walks the **spine** — spec → plan → build. Everything off it
+        (blocking, deferring, rejecting) has to be named explicitly. That is the whole
+        reason there is a machine here rather than a rename: a transition is refused
+        when the destination's requirements are not already met, and that refusal is
+        information — it means the phase has not actually happened yet.
+
+      MARKDOWN
+    end
+
+    # The picture is a hand-drawn PNG, not the mermaid block, because mermaid
+    # lays fifteen states out in a way nobody wants to read.
+    #
+    # The mermaid source is still emitted underneath it, and still derived from
+    # the machine — which is precisely what makes it the staleness check for a
+    # hand-drawn image. Regenerating this document rewrites that block from
+    # {STATUSES} and {StateMachine.inbound}, so a diff there means the PNG no
+    # longer matches. No diff there, no redraw.
+    #
+    # @return [String]
+    def diagram
+      edges = StateMachine.inbound.flat_map { |to, froms|
+        froms.map { |from| "    #{from} --> #{to}" }
+      }
+
+      <<~MARKDOWN
+
+        <details>
+        <summary>Mermaid source for the diagram above</summary>
+
+        ```mermaid
+        stateDiagram-v2
+            direction LR
+        #{Agentilda::STATUSES.map { |s| "    #{s.key} : #{s.emoji} #{s.label}" }.join("\n")}
+
+        #{edges.join("\n")}
+        ```
+
+        </details>
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def files_section
+      known = Agentilda::STATUSES
+        .flat_map(&:requires)
+        .uniq
+        .map { |f| "| `#{f}` | #{holders_of(f)} |" }
+
+      <<~MARKDOWN
+        ## Files allowed in a plan folder
+
+        | File | Required by |
+        | :--- | :---------- |
+        | `spec.md` | the specification; written first |
+        | `plan.md` | the execution plan; written from the spec |
+        #{known.reject { |r| r.start_with?("| `spec.md`", "| `plan.md`") }.join("\n")}
+
+        Nothing else belongs there. A folder holding notes, diagrams or scratch files
+        is a folder nobody can audit at a glance.
+
+      MARKDOWN
+    end
+
+    # @param file [String]
+    # @return [String]
+    def holders_of(file)
+      Agentilda::STATUSES
+        .select { |s| s.requires.include?(file) }
+        .map { |s| "#{s.emoji} #{s.label}" }
+        .join(", ")
+    end
+
+    # @return [String]
+    def pull_requests
+      <<~MARKDOWN
+        ## Pull requests carry the number
+
+        A pull request that implements a plan says so in its title:
+
+        ```
+        [003.00] Make the core deterministic and require as_of
+        ```
+
+        `pull-requests.md` is generated from these titles, so the prefix is the join key
+        between a pull request and a plan, not decoration. Name branches
+        `<user>/NNN.MM-slug` and the number carries itself from branch creation through
+        to a merged, squashed pull request with nobody having to remember it.
+
+        `agentilda resync prs` fills in missing prefixes. It reads the branch name
+        first and falls back to the diff only when that touches exactly one plan folder.
+        **It refuses rather than guessing.** A wrong number does not announce itself: it
+        files the work under a plan that did not do it, and leaves the plan that did
+        looking untouched.
+
+        ### `[#{Agentilda::NO_PLAN_PREFIX}]` when there is no plan
+
+        Not every pull request implements a feature. Dependency bumps, CI configuration,
+        hotfixes and developer tooling implement no plan, and forcing a number onto them
+        produces a number chosen to satisfy the rule. Those are titled:
+
+        ```
+        [#{Agentilda::NO_PLAN_PREFIX}] Bump json from 2.21.1 to 2.21.2
+        ```
+
+        `#{Agentilda::NO_PLAN_PREFIX}` means **"this deliberately belongs to no specification"**, and it
+        exists so that "no plan" is *asserted* rather than merely absent. A title with no
+        prefix is ambiguous between "no plan applies" and "nobody looked".
+
+        `resync prs` will propose it, but marks every such title as **assumed** and never
+        applies one without you seeing it. Emitting it silently on a failed lookup would
+        launder "I could not tell" into "there is definitely none", which is the same
+        lie as guessing a number, told in the other direction.
+
+        ### What does not deserve a retroactive plan
+
+        Most unmatched pull requests. The test is whether **somebody would need to read
+        it** — a capability with behaviour, an interface, or invariants that are not
+        obvious from the code. "Fix a typo", "remove dead code" and "bump a dependency"
+        are `[#{Agentilda::NO_PLAN_PREFIX}]` and always were. Backfilling those produces an index that is
+        longer without being more informative, which makes the real plans harder to find.
+
+      MARKDOWN
+    end
+
+    # @return [String]
+    def footer
+      <<~MARKDOWN
+        ## If a real issue tracker arrives, this scheme retires
+
+        This numbering is homegrown because there is nothing else to join on. If the
+        work moves to Linear or Jira, **the issue key replaces it**: `[EQL-142] <title>`
+        in pull request titles, `EQL-142-<status>-<slug>` for the folder, and the issue
+        becomes the thing `pull-requests.md` is generated against.
+
+        Recording that matters more than it looks. A numbering scheme with no stated
+        exit becomes permanent by default: it accretes tooling, the tooling accretes
+        rules, and by the time a real tracker shows up, migrating is a project rather
+        than a decision. The exit is cheap only while it is written down and unbuilt.
+
+        Two things to hold to when that day comes:
+
+        - **Existing numbers are not rewritten.** A plan's number is its identity and
+          merged pull request titles are immutable history. `000` stays `000` forever and
+          new plans start taking issue keys. A mixed index is ugly for a while and honest
+          permanently, which beats a renumbering that breaks every link that ever pointed
+          at a plan.
+        - **Do not teach the tooling to accept issue keys before the tracker exists.** A
+          validator that accepts `[EQL-142]` with nothing to check it against is a guard
+          that passes anything shaped like an answer, which is worse than one that fails
+          loudly on first use.
+
+        ______________________________________________________________________
+
+        Generated by `agentilda docs` — version #{Agentilda::VERSION}.
+      MARKDOWN
+    end
+
+    # @param key [Symbol]
+    # @return [Agentilda::Status]
+    def status(key) = Agentilda::STATUS_BY_KEY.fetch(key)
+  end
+end