@kitman-sh/software-engineering 0.10.58 → 0.10.59

package/dist/declarations.json

@@ -337,6 +337,39 @@
                     "type": "integer",
                     "minimum": -9007199254740991,
                     "maximum": 9007199254740991
+                  },
+                  "release": {
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "runStatus": {
+                            "type": "string"
+                          },
+                          "reason": {
+                            "type": "string"
+                          },
+                          "tag": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          }
+                        },
+                        "required": [
+                          "runStatus",
+                          "reason"
+                        ],
+                        "additionalProperties": true
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
                   }
                 },
                 "required": [
@@ -418,7 +451,9 @@
         "call",
         "ask",
         "read_change_request",
-        "merge_change_request"
+        "merge_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -542,7 +577,9 @@
         "post_comment",
         "approve_change_request",
         "read_change_request",
-        "merge_change_request"
+        "merge_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -886,7 +923,9 @@
         "post_comment",
         "read_change_request",
         "merge_change_request",
-        "approve_change_request"
+        "approve_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -1068,7 +1107,9 @@
         "post_comment",
         "approve_change_request",
         "read_change_request",
-        "merge_change_request"
+        "merge_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -1360,7 +1401,9 @@
         "merge_change_request",
         "read_change_request",
         "post_comment",
-        "approve_change_request"
+        "approve_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -1509,6 +1552,7 @@
               "deployed",
               "rolled_back",
               "deploy_failed",
+              "rollback_failed",
               "timed_out"
             ]
           },
@@ -1564,7 +1608,8 @@
         "$defs": {}
       },
       "agents": {
-        "releaser": "releaser"
+        "releaser": "releaser",
+        "deployer": "deployer"
       },
       "checkout": "read",
       "when": [],
@@ -1950,7 +1995,9 @@
         "post_comment",
         "approve_change_request",
         "read_change_request",
-        "merge_change_request"
+        "merge_change_request",
+        "claim",
+        "publish_release"
       ],
       "schedule": {
         "rule": {
@@ -2401,7 +2448,9 @@
         "write_back",
         "read_change_request",
         "merge_change_request",
-        "approve_change_request"
+        "approve_change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -2573,6 +2622,39 @@
             "type": "integer",
             "minimum": -9007199254740991,
             "maximum": 9007199254740991
+          },
+          "release": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "runStatus": {
+                    "type": "string"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "tag": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  }
+                },
+                "required": [
+                  "runStatus",
+                  "reason"
+                ],
+                "additionalProperties": true
+              },
+              {
+                "type": "null"
+              }
+            ]
           }
         },
         "required": [
@@ -2600,7 +2682,9 @@
         "write_back",
         "ask",
         "verify",
-        "change_request"
+        "change_request",
+        "claim",
+        "publish_release"
       ]
     },
     {
@@ -2798,7 +2882,9 @@
         "post_comment",
         "approve_change_request",
         "write_back",
-        "ask"
+        "ask",
+        "claim",
+        "publish_release"
       ],
       "schedule": {
         "rule": {
@@ -2964,6 +3050,8 @@
         "read_change_request",
         "merge_change_request",
         "approve_change_request",
+        "claim",
+        "publish_release",
         "create_tasks"
       ]
     }
@@ -3032,6 +3120,15 @@
         "shipping-and-launch"
       ]
     },
+    "deployer": {
+      "instructions": "You are a deployer. Release has tagged a version, and you run the repository's own deploy script for it, once.\n\n## Boundaries\n\n- Run only the command your brief names. Do not edit files, commit, push, tag, merge or retry it: the script backs up, publishes, deploys, verifies and rolls back by itself.\n- It runs for a long time. Start it once in the background with its output in a log file, and wait for it to exit.\n- Never print, copy or summarise the variables, tokens or secrets it pulls, or the production host's address.\n\n## Output\n\nSubmit your Output with the Kitman MCP `submit_output` tool, in the shape the brief's Output schema gives.",
+      "effort": "low",
+      "fallbacks": [
+        {
+          "harness": "pi"
+        }
+      ]
+    },
     "investigator": {
       "instructions": "You are an investigator. You find out why something happened and report a conclusion you can support.\n\n## Investigation\n\n- Start from the evidence you are given: the alert, its logs, metrics and traces, and the code that produced them.\n- You have web tools: read an upstream issue, a changelog or the documentation of a dependency when the evidence points outside the repository.\n- Form a hypothesis, then look for what would prove it wrong. Report what the evidence shows, not what you expected.\n- Every conclusion cites its sources: the log line, the query, the commit or the file and line it rests on.\n- Separate what you established from what you suspect, and say how sure you are.\n- When the cause points to a code change, describe the fix precisely enough that a Build can make it, but do not make it yourself.\n\n## Boundaries\n\n- Change nothing: do not edit files, commit, push or merge. The Run owns the branch.\n- Never `git stash`: the stash stack is shared with every other worktree of the repository. To look at another revision, make a throwaway checkout with `git worktree add` and remove it after.\n- A finding written in your Output is a claim. Say what you ran and what it returned.\n\n## Output\n\nSubmit your Output with the Kitman MCP `submit_output` tool, in the shape the brief's Output schema gives. An answer with no fix is a real outcome.",
       "effort": "high",
@@ -3090,7 +3187,7 @@
   "carried": [
     {
       "name": "@kitman-sh/software-engineering",
-      "version": "0.10.58",
+      "version": "0.10.59",
       "setup": "2a237548a69b0cd53ec3be7f687cfa8c2128335b3a655d34e185f2abce6a3c37",
       "loops": [
         "build",
@@ -3115,6 +3212,7 @@
         "quality-reviewer",
         "planner",
         "releaser",
+        "deployer",
         "investigator",
         "climber",
         "surveyor",

package/kitman.config.ts

@@ -73,6 +73,11 @@ export default defineKit({
       skills: ['git-workflow-and-versioning', 'shipping-and-launch'],
       instructions: { file: 'agents/releaser.md' }
     },
+    deployer: {
+      effort: 'low',
+      fallbacks,
+      instructions: { file: 'agents/deployer.md' }
+    },
     investigator: {
       effort: 'high',
       fallbacks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitman-sh/software-engineering",
-  "version": "0.10.58",
+  "version": "0.10.59",
   "description": "Everything for building software: Loops, their Agents, the skills they use and the Ponytail plugin.",
   "type": "module",
   "license": "UNLICENSED",
@@ -17,12 +17,12 @@
     "tsconfig.json"
   ],
   "dependencies": {
-    "@kitman-sh/sdk": "0.10.58",
+    "@kitman-sh/sdk": "0.10.59",
     "effect": "4.1.2"
   },
   "kitman": {
     "bundle": "dist/bundle.js",
-    "digest": "ed3f43456848d81db262c65cd16fbbc8ae2683d7b6f44a0348c0de96507e0319",
+    "digest": "c865bc195025830b0c1056823b84a8a14ff3315d5c68fbe5da62ca246d862fee",
     "protocolVersion": 5,
     "declarations": "dist/declarations.json",
     "setup": {

package/src/build.ts

@@ -1,5 +1,6 @@
 import {
   agentWork,
+  ask,
   agentWorkOnce,
   approveChangeRequest,
   ApproveChangeRequestResult,
@@ -516,8 +517,9 @@ export default defineLoop({
             )
           : undefined
 
+      // A blocking Review, or anything else left unsettled, stops here with the findings for a person, not in Shepherd.
       const landed =
-        input.land !== false
+        input.land !== false && unsettled.length === 0
           ? yield* call('land', shepherd, {
               changeRequestId: opened.id,
               ...(input.taskId === undefined ? undefined : { taskId: input.taskId }),
@@ -525,6 +527,16 @@ export default defineLoop({
             })
           : undefined
 
+      if (input.land !== false && unsettled.length > 0)
+        yield* ask('unsettled', {
+          prompt: `The ChangeRequest ${opened.url} is open, but these still stand: ${unsettled.join('; ')}. Build will not land it.`,
+          options: [{ value: 'Taken over', description: 'A person fixes, rebuts or steers it from here.' }],
+          recommended: 'Taken over',
+          recommendationReason: 'Build stopped with these unsettled, so the next step is a person’s.',
+          // No default: an unattended Run, as full auto starts, would take it at once and finish as partial.
+          default: null
+        })
+
       return {
         changeRequest: opened,
         revision: last.head.revision,

package/src/release.ts

@@ -43,6 +43,22 @@ const Drafted = Schema.Struct({
 
 type Drafted = typeof Drafted.Type
 
+/** What the repository's own deploy script did, as the releaser read it from its last line and exit code. */
+const Deployed = Schema.Struct({
+  /** none: the repository has no `.kitman/deploy`, so the deploy is left to whatever sends the deploy Event. */
+  status: Schema.Literals(['deployed', 'failed', 'rolled_back', 'rollback_failed', 'none']),
+  detail: Schema.String
+})
+
+const deployPrompt = (tag: string, previousTag: string | undefined) =>
+  [
+    `Deploy the release ${tag}, which Kitman has just tagged and pushed.`,
+    `If the repository has no executable \`.kitman/deploy\` at ${tag}, change nothing and answer status none.`,
+    `Otherwise run \`.kitman/deploy ${tag}${previousTag === undefined ? '' : ` ${previousTag}`}\` from the checkout of ${tag} (\`git fetch --tags\` first), and do nothing else: it backs up, publishes, deploys, verifies and rolls back by itself, and may take an hour. Run it in the background with its output in a log file, and wait for it to exit, checking every few minutes; never start it twice.`,
+    'Answer with the status its last line `kitman-deploy: <status> <detail>` names, and that detail. If it exited without that line, answer failed with its exit code and the end of its log.',
+    'Never print, copy or summarise the variables or secrets it pulls.'
+  ].join('\n\n')
+
 const Output = Schema.Struct({
   status: Schema.Literals([
     'gate_failed',
@@ -51,6 +67,8 @@ const Output = Schema.Struct({
     'deployed',
     'rolled_back',
     'deploy_failed',
+    /** The deploy failed after production changed, and so did the rollback: production may be broken. */
+    'rollback_failed',
     'timed_out'
   ]),
   /** Why it stopped, or what happened, in a line. */
@@ -189,7 +207,7 @@ export default defineLoop({
   title: 'Release',
   input: Input,
   output: Output,
-  agents: { releaser: 'releaser' },
+  agents: { releaser: 'releaser', deployer: 'deployer' },
   checkout: 'read',
   capabilities: [
     'agent_work',
@@ -247,7 +265,9 @@ export default defineLoop({
           recommended: 'Approve',
           recommendationReason:
             'The release is proved: its checks pass, or its ChangeRequest is green, approved and mergeable.',
-          default: null
+          default: null,
+          // A full-auto Team has handed releasing a proved change to Kitman.
+          auto: 'Approve'
         })
 
         if (answer === 'Approve') break
@@ -360,6 +380,35 @@ export default defineLoop({
         )
 
       const settled = { tag, notesArtifactId: notes.artifactId, revision: released.revision, url: released.url }
+
+      // The repository deploys itself from the Runner when it has a deploy script, which rolls back on its own.
+      const ran = yield* agentWork('run-deploy', {
+        agent: 'deployer',
+        prompt: deployPrompt(tag, drafted.previousTag),
+        output: Deployed,
+        timeout: '3 hours'
+      })
+
+      if (ran.status !== 'none') {
+        const status = ran.status === 'failed' ? 'deploy_failed' : ran.status
+
+        const outcome = {
+          deployed: 'deployed',
+          rolled_back: 'rolled back',
+          deploy_failed: 'failed to deploy',
+          rollback_failed: 'failed to deploy, and the rollback failed too'
+        }[status]
+
+        yield* artifact('report', {
+          kind: 'release_report',
+          title: `${tag} ${outcome}`,
+          text: `${tag} at ${released.revision}: ${ran.detail}. ${released.url}`,
+          data: { tag, status, revision: released.revision, url: released.url, detail: ran.detail }
+        })
+
+        return { status, reason: ran.detail, ...settled } satisfies Output
+      }
+
       let status = yield* deployed('deploy', tag)
 
       for (let round = 1; status !== 'deployed'; round++) {

package/src/review.ts

@@ -270,14 +270,25 @@ export default defineLoop({
       const earlier = input.earlier ?? []
       const earlierIds = new Set(earlier.map(finding => finding.id))
 
-      const followUps = followUpsOf(
+      const answered = followUpsOf(
         earlier,
         outputs.flatMap(([, output]) => output.followUps ?? [])
       )
 
-      const standing = new Set(followUps.flatMap(entry => (entry.status === 'fixed' ? [] : [entry.id])))
+      const standing = new Set(answered.flatMap(entry => (entry.status === 'fixed' ? [] : [entry.id])))
 
-      const carried = earlier.filter(finding => standing.has(finding.id))
+      const verdicts = outputs.flatMap(([, output]) => output.verdicts ?? [])
+      const rebutted = new Set((input.rebuttals ?? []).map(rebuttal => rebuttal.findingId))
+
+      // A rebutted finding every verdict on it accepts is withdrawn, as Build's settleRound counts it.
+      const withdrawn = (id: string) => {
+        const on = verdicts.filter(verdict => verdict.findingId === id)
+
+        return rebutted.has(id) && on.length > 0 && on.every(verdict => verdict.accepted)
+      }
+
+      const carried = earlier.filter(finding => standing.has(finding.id) && !withdrawn(finding.id))
+      const followUps = answered.filter(entry => !withdrawn(entry.id))
 
       const fresh = mergeFindings(
         Object.fromEntries(
@@ -290,14 +301,24 @@ export default defineLoop({
 
       const findings = [...carried, ...fresh]
 
+      const blockers = findings.filter(isBlocking)
+      const scope = input.files === undefined ? outputs.find(([seat]) => seat === scopeSeat)?.[1].scope : undefined
+      const failing = input.failing ?? []
+
+      // A seat's own summary is kept only when nothing blocks, so it cannot contradict the verdict.
       const summary =
-        findings.length === 0
-          ? 'No findings: nothing stands in the way of merging.'
-          : outputs.map(([, output]) => output.summary).join(' ')
+        blockers.length > 0
+          ? `Blocking: fix ${blockers.map(finding => finding.id).join(', ')} before merging.`
+          : scope?.met === false
+            ? 'Not ready: the change does not yet do what was asked.'
+            : failing.length > 0
+              ? `Not ready: ${failing.join(', ')} fails on this head.`
+              : findings.length === 0
+                ? 'No findings: nothing stands in the way of merging.'
+                : ['Can merge: nothing blocks it.', ...outputs.map(([, output]) => output.summary)].join(' ')
 
       const freshIds = new Set(fresh.map(finding => finding.id))
       const text = reviewText(summary, findings, followUps)
-      const scope = input.files === undefined ? outputs.find(([seat]) => seat === scopeSeat)?.[1].scope : undefined
 
       const stored = yield* artifact('findings', {
         kind: 'review-findings',
@@ -310,7 +331,7 @@ export default defineLoop({
         summary,
         findings,
         followUps,
-        verdicts: outputs.flatMap(([, output]) => output.verdicts ?? []),
+        verdicts,
         blocking: findings.some(isBlocking),
         artifactId: stored.artifactId,
         ...(scope === undefined ? undefined : { scope })
@@ -321,7 +342,7 @@ export default defineLoop({
       if (changeRequestId === undefined || head === undefined) return reviewed
 
       const approval =
-        reviewed.blocking || scope?.met === false || (input.failing?.length ?? 0) > 0
+        reviewed.blocking || scope?.met === false || failing.length > 0
           ? undefined
           : yield* approveChangeRequest('approve', { changeRequestId, head, summary }).pipe(
               Effect.map(result =>

package/src/shepherd-output.ts

@@ -6,5 +6,9 @@ export const ShepherdOutput = Schema.Struct({
   /** Why it stopped, in a line a person can act on. */
   reason: Schema.String,
   fixRounds: Schema.Int,
-  replies: Schema.Int
+  replies: Schema.Int,
+  /** The Release it started after merging, when it was told to release. */
+  release: Schema.optional(
+    Schema.Struct({ runStatus: Schema.String, reason: Schema.String, tag: Schema.optional(Schema.String) })
+  )
 })

package/src/shepherd.ts

@@ -25,6 +25,7 @@ import {
 } from '@kitman-sh/sdk/loop'
 import * as Effect from 'effect/Effect'
 import * as Schema from 'effect/Schema'
+import release from './release'
 import review, { ReviewInput, ReviewOutput } from './review'
 import { ShepherdOutput } from './shepherd-output'
 
@@ -160,7 +161,7 @@ export default defineLoop({
     'ask',
     'verify'
   ],
-  calls: (): readonly CalledLoop[] => [review],
+  calls: (): readonly CalledLoop[] => [review, release],
   run: input => {
     const changeRequestId = input.changeRequestId
     // The ChangeRequest's own target: an offer's `branch` may be the offering Run's branch, which is this one.
@@ -486,6 +487,8 @@ export default defineLoop({
                 recommended: 'Merge',
                 recommendationReason: 'It is approved, green and mergeable, which is everything a merge waits for.',
                 default: 'Wait',
+                // A full-auto Team merges what its Review approved and its checks passed.
+                auto: 'Merge',
                 timeout: '1 hour'
               })
 
@@ -500,7 +503,42 @@ export default defineLoop({
         if (merged.status !== 'merged') continue
         yield* writeBack('write-back', { milestone: 'merged' })
 
-        return done('merged', `Merged at ${merged.revision}`)
+        const ship = yield* ask('ship', {
+          prompt: `Merged at ${merged.revision}. Release it now?`,
+          options: [
+            { value: 'Release', description: 'Starts Release on the merge: it gates, tags, publishes and deploys it.' },
+            { value: 'Not now', description: 'Leaves the release to a person or a later Release.' }
+          ],
+          recommended: 'Release',
+          recommendationReason: 'The merge is approved and green, so it is ready to ship.',
+          default: 'Not now',
+          auto: 'Release',
+          timeout: '1 hour'
+        })
+
+        if (ship === 'Not now') return done('merged', `Merged at ${merged.revision}`)
+
+        const released = yield* call('release', release, { revision: merged.revision })
+
+        // It merged either way; a Release that did not deploy, other than one a person rejected, needs a person.
+        if (released.status !== 'deployed' && released.status !== 'rejected')
+          yield* ask('release-failed', {
+            prompt: `Merged at ${merged.revision}, but its Release ended ${released.status}: ${released.reason}`,
+            options: [{ value: 'Taken over', description: 'A person looks at the release and production from here.' }],
+            recommended: 'Taken over',
+            recommendationReason: 'The merge is in, but production may not run it, or may be broken.',
+            // No default: full auto runs unattended, and would take it at once and finish as merged.
+            default: null
+          })
+
+        return {
+          ...done('merged', `Merged at ${merged.revision}; Release: ${released.reason}`),
+          release: {
+            runStatus: released.status,
+            reason: released.reason,
+            ...(released.tag === undefined ? undefined : { tag: released.tag })
+          }
+        }
       }
     }).pipe(
       // Kitman fails a Step that runs past its time budget with this reason.