nilstate/runx

Evolve

Evolua o repositório atual por meio de fases governadas com semântica fixa e revisão opcional limitada. Sem objetivo, o comportamento padrão é introspectivo: analisar o repositório, recomendar uma melhoria limitada e parar em um conjunto de artefatos de qualidade de plano.

Isso não é geração de código autônoma. Ele governa a forma em torno da cognição — cada fase produz um artefato tipado, cada mutação requer aprovação, cada etapa emite um recibo. Uma única execução do evolve termina em um artefato limitado, não em um loop de melhoria aberto.

Semântica canônica

Habilidades runx complexas compartilham uma linguagem de fase interna:

• scope
• ingest
• model
• materialize
• evaluate
• revise
• verify
• ratify

O runner evolve atual usa um subconjunto limitado e comprime algumas fases em menos etapas concretas. Isso é permitido. O que permanece fixo é o significado das fases, não o número de etapas.

Mapeamento atual do runner

Introspect

Mediado pelo chamador (etapa do agente). Esta é a via de recomendação sem argumentos. Ela usa scope + ingest + model para analisar o repositório atual e produzir:

• opportunity_report — oportunidades ranqueadas baseadas em evidências do repositório
• recommended_objective — um próximo movimento limitado
• change_plan — um plano concreto para essa recomendação
• spec_document — um esboço preliminar de especificação no estilo scafld quando a governança se aplica

Não há portão de aprovação e nenhuma mutação neste runner. É introspecção apenas.

Preflight

Determinístico. Esta é a etapa atual de scope + ingest. Ela inspeciona o repositório alvo e produz um repo_profile: raiz do repositório, estado do git, branch base, árvore de trabalho suja, presença de .ai/ (scafld inicializado), linguagens detectadas, comandos de teste, sinais de risco. Sem cognição do agente, sem mutação.

Plan

Mediado pelo chamador (etapa do agente). Esta é a etapa atual de model e também elabora artefatos de plano limitados. Dado o objetivo e o perfil do repositório, ela produz quatro artefatos em uma passagem:

• objective_brief — reformulação com tipo de alvo, restrições, critérios de sucesso.
• diagnosis_report — estado atual do repositório em relação ao objetivo.
• change_plan — fases ordenadas, verificações de aceitação, pontos de contato, risco.
• spec_document — esboço de especificação scafld quando a governança se aplica.

Guarda de término

Atualmente, evolve para em artefatos de plano/especificação. Se um chamador solicitar terminate=patch ou terminate=pr, o runner falha imediatamente com um erro claro em vez de fingir que pode sofrer mutação ou publicar.

Política de revisão

Atualmente, evolve não realiza rodadas de revisão. Isso é intencional. Quando a revisão limitada for introduzida, ela deve ser explícita e controlada por políticas, por exemplo max_rounds: 1 ou 2, com condições de parada e escalonamento definidas.

Modos de invocação

• runx evolve — introspectar o repositório atual e recomendar uma melhoria limitada
• runx evolve "<objetivo>" — planejar uma mudança direcionada
• runx evolve "<objetivo>" --terminate patch|pr — atualmente rejeitado até que uma via de execução real exista

Alvos de evolução

A string de objetivo determina o alvo. A fase de pré-verificação resolve o alvo concreto a partir do contexto do repositório atual.

• Repositório: "adicionar suporte a adaptador websocket" — melhorar a base de código em direção a um objetivo.
• Habilidade: --skill ./skills/sourcey — melhorar um pacote de habilidade específico.
• Recibo: --receipt rx_8f3a — reparar com base em uma execução falha.
• Auto: executar contra o próprio repositório runx no campo de provas.

Término

• spec (padrão): parar após o planejamento. Sem mutação.
• patch: ainda não suportado neste runner enviado.
• pr: ainda não suportado neste runner enviado.

Regras de limite

• Uma única execução do evolve termina em um artefato limitado, não em outro loop oculto.
• A política avalia campos estruturados, nunca prosa.
• Se a execução for adicionada posteriormente, ela deve rotear por ferramentas reais, scafld, ou outras vias governadas em vez de etapas internas sintéticas.

Entradas

• objective (opcional): para o que evoluir. Se omitido, evolve usa o runner de recomendação introspectiva.
• repo_root (opcional): raiz do repositório. Padrão é o diretório atual.
• terminate (opcional): padrão é spec. Outros valores são atualmente rejeitados pelo runner enviado.