@lchase/kiln 0.0.0-stage → 0.3.0

package/prompts/kiln/code.md

@@ -0,0 +1,26 @@
+<!-- factory: prompts/factory/review-code.md -->
+
+Kiln runs this factory reviewer inside yak. The working directory is the worktree. There is no job folder, no round folder, and no `.factory/repo.md`; read the repo for conventions. `.factory/lessons.md` applies only when that file is really present.
+
+`<main branch>` is the base SHA `{{input.baseRef}}` (the commit this worktree was branched from). Use that SHA wherever the factory instructions say `<main branch>`, including `git diff <main branch>...HEAD`, merge-tree, and ahead-of checks. Do not guess `main`.
+
+Your branch is whatever `git branch --show-current` prints. It is `yak/<run-id>`. That is the branch name in this prompt. Do not BLOCK because it is not `factory/...` or `main`.
+
+Do not write `review-code.md`. Return JSON `{ "verdict": "PASS" or "CHANGES", "findings": "the rest of that file" }`. `verdict` is the VERDICT line. `spec.md` and `build.md` are the text below, not files. Call the smart-review skill the way the factory instructions say (`smart-review:smart-review`, min mode). Skill is available. There is no `spec.md` path on disk; use the spec text below as the spec. Your previous review is not a separate file.
+
+Spec goal: {{spec.goal}}
+Spec design: {{spec.design}}
+Spec acceptance: {{spec.acceptance}}
+
+Build ({{build.status}}): {{build.summary}}
+
+Verify ran the repo test command. A non-zero exit is a failure:
+exit {{verify.exitCode}}
+stdout: {{verify.stdout}}
+stderr: {{verify.stderr}}
+
+Verify stdout and stderr may be truncated to the last 200 lines or 20480 bytes. A leading `[truncated:` line means the head was cut.
+
+Use the verify output provided; do not re-run tests, builds, or anything that writes to the working tree. Read-only git and file inspection only.
+
+The factory agent instructions follow. Their frontmatter is the original definition. Follow that prose except where it says to re-run tests or builds, or to write a file. Return the JSON above instead of writing the file they name.

package/prompts/kiln/investigation.md

@@ -0,0 +1,31 @@
+Kiln runs this investigation inside yak. The working directory is an isolated worktree of the repo at base SHA `{{input.baseRef}}`. That SHA is the commit to inspect. Do not guess a branch name.
+
+Explore the tree and answer the questions in the spec. You may run commands and scripts. You must not change product code. Do not create, modify, or delete files. Do not commit, push, or open a pull request. Do not run formatters, package installs, or anything else that writes. Read-only git and file inspection are allowed. This step has no Write or Edit tool.
+
+Do not write a findings file. Return JSON with one string field, `markdown`. Kiln stores that markdown after a person approves it, and later jobs read it. The markdown is the whole document, not a fragment.
+
+Use these headings, in this order, spelled exactly:
+
+# Findings: {{input.title}}
+
+## Questions
+
+The questions the spec asks, as a list.
+
+## Answers
+
+One subsection per question. State the answer, then the evidence. Evidence is file paths and command output you actually observed in this worktree. Do not invent paths or output. If you did not run a command, do not claim you did.
+
+## Unconfirmed
+
+What you could not confirm, and what you looked at. Write "None." when nothing is left open.
+
+## Implications for dependent tickets
+
+What a later ticket should rely on, and what it must not assume.
+
+Spec title: {{input.title}}
+
+{{input.spec}}
+
+Launch id: {{input.runNonce}}

package/prompts/kiln/security.md

@@ -0,0 +1,26 @@
+<!-- factory: prompts/factory/review-security.md -->
+
+Kiln runs this factory reviewer inside yak. The working directory is the worktree. There is no job folder, no round folder, and no `.factory/repo.md`; read the repo for conventions. `.factory/lessons.md` applies only when that file is really present.
+
+`<main branch>` is the base SHA `{{input.baseRef}}` (the commit this worktree was branched from). Use that SHA wherever the factory instructions say `<main branch>`, including `git diff <main branch>...HEAD`, merge-tree, and ahead-of checks. Do not guess `main`.
+
+Your branch is whatever `git branch --show-current` prints. It is `yak/<run-id>`. That is the branch name in this prompt. Do not BLOCK because it is not `factory/...` or `main`.
+
+Do not write `review-security.md`. Return JSON `{ "verdict": "PASS" or "CHANGES", "findings": "the rest of that file" }`. `verdict` is the VERDICT line. `spec.md` and `build.md` are the text below. Your previous review is not a separate file.
+
+Spec goal: {{spec.goal}}
+Spec design: {{spec.design}}
+Spec acceptance: {{spec.acceptance}}
+
+Build ({{build.status}}): {{build.summary}}
+
+Verify ran the repo test command. A non-zero exit is a failure:
+exit {{verify.exitCode}}
+stdout: {{verify.stdout}}
+stderr: {{verify.stderr}}
+
+Verify stdout and stderr may be truncated to the last 200 lines or 20480 bytes. A leading `[truncated:` line means the head was cut.
+
+Use the verify output provided; do not re-run tests, builds, or anything that writes to the working tree. Read-only git and file inspection only.
+
+The factory agent instructions follow. Their frontmatter is the original definition. Follow that prose except where it says to re-run tests or builds, or to write a file. Return the JSON above instead of writing the file they name.

package/prompts/kiln/spec.md

@@ -0,0 +1,18 @@
+<!-- factory: prompts/factory/spec-writer.md -->
+
+Kiln runs this factory agent inside yak. The working directory is the worktree. There is no `.factory/` job folder and no `.factory/repo.md`; read the repo for conventions. `.factory/lessons.md` applies only when that file is really present.
+
+`<main branch>` is the base SHA `{{input.baseRef}}` (the commit this worktree was branched from). Use that SHA wherever the factory instructions say `<main branch>`, including `git diff <main branch>...HEAD`, merge-tree, and ahead-of checks. Do not guess `main`.
+
+Your branch is whatever `git branch --show-current` prints. It is `yak/<run-id>`. That is the branch name in this prompt. Do not BLOCK because it is not `factory/...` or `main`.
+
+`feature.md` is the task below, not a file. Do not write `spec.md`. Return JSON: `goal` (the Goal paragraph), `design` (Scope, Design, and Deferred), `acceptance` (the acceptance criteria and the Verify commands). Do not write code.
+
+Task title: {{input.title}}
+
+{{input.description}}
+
+Acceptance:
+{{input.acceptance}}
+
+The factory agent instructions follow. Their frontmatter is the original definition; follow the prose, and return the JSON above instead of writing the file they name.

package/prompts/kiln/ui.md

@@ -0,0 +1,26 @@
+<!-- factory: prompts/factory/review-ui.md -->
+
+Kiln runs this factory reviewer inside yak. The working directory is the worktree. There is no job folder, no round folder, and no `.factory/repo.md` (so there is no `## UI paths` file; look at the diff). `.factory/lessons.md` applies only when that file is really present.
+
+`<main branch>` is the base SHA `{{input.baseRef}}` (the commit this worktree was branched from). Use that SHA wherever the factory instructions say `<main branch>`, including `git diff <main branch>...HEAD`, merge-tree, and ahead-of checks. Do not guess `main`.
+
+Your branch is whatever `git branch --show-current` prints. It is `yak/<run-id>`. That is the branch name in this prompt. Do not BLOCK because it is not `factory/...` or `main`.
+
+This step always runs. The factory instructions below already return PASS when no UI changed. Do not write `review-ui.md`. Return JSON `{ "verdict": "PASS" or "CHANGES", "findings": "the rest of that file" }`. `verdict` is the VERDICT line. `spec.md` and `build.md` are the text below. Your previous review is not a separate file.
+
+Spec goal: {{spec.goal}}
+Spec design: {{spec.design}}
+Spec acceptance: {{spec.acceptance}}
+
+Build ({{build.status}}): {{build.summary}}
+
+Verify ran the repo test command. A non-zero exit is a failure:
+exit {{verify.exitCode}}
+stdout: {{verify.stdout}}
+stderr: {{verify.stderr}}
+
+Verify stdout and stderr may be truncated to the last 200 lines or 20480 bytes. A leading `[truncated:` line means the head was cut.
+
+Use the verify output provided; do not re-run tests, builds, or anything that writes to the working tree. Read-only git and file inspection only.
+
+The factory agent instructions follow. Their frontmatter is the original definition. Follow that prose except where it says to re-run tests or builds, or to write a file. Return the JSON above instead of writing the file they name.

package/prompts/kiln/ux.md

@@ -0,0 +1,26 @@
+<!-- factory: prompts/factory/review-ux.md -->
+
+Kiln runs this factory reviewer inside yak. The working directory is the worktree. There is no job folder, no round folder, and no `.factory/repo.md`; read the repo for conventions. `.factory/lessons.md` applies only when that file is really present.
+
+`<main branch>` is the base SHA `{{input.baseRef}}` (the commit this worktree was branched from). Use that SHA wherever the factory instructions say `<main branch>`, including `git diff <main branch>...HEAD`, merge-tree, and ahead-of checks. Do not guess `main`.
+
+Your branch is whatever `git branch --show-current` prints. It is `yak/<run-id>`. That is the branch name in this prompt. Do not BLOCK because it is not `factory/...` or `main`.
+
+Do not write `review-ux.md`. Return JSON `{ "verdict": "PASS" or "CHANGES", "findings": "the rest of that file" }`. `verdict` is the VERDICT line. `spec.md` and `build.md` are the text below. Your previous review is not a separate file.
+
+Spec goal: {{spec.goal}}
+Spec design: {{spec.design}}
+Spec acceptance: {{spec.acceptance}}
+
+Build ({{build.status}}): {{build.summary}}
+
+Verify ran the repo test command. A non-zero exit is a failure:
+exit {{verify.exitCode}}
+stdout: {{verify.stdout}}
+stderr: {{verify.stderr}}
+
+Verify stdout and stderr may be truncated to the last 200 lines or 20480 bytes. A leading `[truncated:` line means the head was cut.
+
+Use the verify output provided; do not re-run tests, builds, or anything that writes to the working tree. Read-only git and file inspection only.
+
+The factory agent instructions follow. Their frontmatter is the original definition. Follow that prose except where it says to re-run tests or builds, or to write a file. Return the JSON above instead of writing the file they name.

package/workflows/feature.yaml

@@ -0,0 +1,239 @@
+# One Kiln job, run by yak (@lchase/yak).
+#
+# Faithful to Lawrence Chase's factory plugin v0.7.0 (MIT):
+# https://github.com/lchase/coding-agent-plugins/tree/4c84a2ce7fbde5ac298c0de9f0b90141eac4ed98/plugins/factory
+#   skills/factory/SKILL.md          (the loop: spec, build, 4 reviews, approver)
+#   agents/spec-writer.md            model opus
+#   agents/builder.md                model opus
+#   agents/review-security.md        model opus
+#   agents/review-ux.md              model sonnet
+#   agents/review-ui.md              model sonnet
+#   agents/review-code.md            model sonnet
+#   agents/approver.md               model opus
+# The prompt bodies are copied verbatim into prompts/factory/. Each step's
+# prompt file is a Kiln preamble (prompts/kiln/) that maps the factory's
+# job-folder files onto yak artifacts and tells the agent to return JSON
+# instead of writing a file. `kiln tick` appends the factory body and rewrites
+# prompt.file to an absolute path under the kiln directory before launching,
+# because yak resolves prompt.file from the checkout cwd
+# (yak src/steps/agent.ts, path.resolve(cwd, file)).
+#
+# yak 0.6.1 limits this file still works inside:
+# - command.run is not templated. verify runs $KILN_TEST through
+#   dist/truncate-output.js ($KILN_VERIFY_WRAPPER). `kiln tick` sets
+#   KILN_TEST from repos.<repo>.test. An empty value fails the step. The
+#   wrapper keeps the test's exit code and cuts stdout/stderr to the last
+#   200 lines or 20KB, with a leading `[truncated:` line when it cuts.
+#   land commits with `git commit -m "kiln: $KILN_TASK_TITLE"`. verify and
+#   land need `input` (it carries a per-launch runNonce) so one job cannot
+#   cache-hit another. land runs only when approval.decision is approve,
+#   and it does not fail when the index is empty. `git add -A` stages every
+#   uncommitted path in the worktree.
+# - input.baseRef is the commit the worktree was branched from (full SHA).
+#   deliver=local uses checkout HEAD. deliver=pr uses origin/<base>, or the
+#   upstream yak/<run-id> tip when the job is stacked. Every preamble maps
+#   `<main branch>` to that SHA. The worktree branch is yak/<run-id>.
+# - A loop body does not evaluate skipIf, so the UI reviewer is a real step.
+#   review-ui.md itself returns PASS when no UI changed.
+# - A loop-body artifact is not a top-level producer. The approver reads the
+#   last verify on rounds.verify; needs: [verify] on the approver is rejected.
+#   Reviewers run inside the loop, so they need verify directly. They inherit
+#   input (for baseRef) instead of listing it in needs, and the loop's
+#   concurrency is 4 so the four reviewers start together.
+name: kiln-feature
+version: "1"
+inputSchema:
+  inline:
+    type: object
+    additionalProperties: false
+    properties:
+      title: { type: string }
+      description: { type: string }
+      acceptance: { type: string }
+      runNonce: { type: string }
+      baseRef: { type: string }
+    required: [title, description, acceptance, runNonce, baseRef]
+steps:
+  - id: spec
+    needs: [input]
+    agent:
+      model: opus
+      prompt:
+        file: prompts/kiln/spec.md
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            goal: { type: string }
+            design: { type: string }
+            acceptance: { type: string }
+          required: [goal, design, acceptance]
+      tools: [Read, Grep, Glob, Bash, Write, Skill]
+    produces: spec
+
+  - id: revise
+    needs: [spec]
+    loop:
+      # A BLOCKED build, a red verify (exitCode != 0), or any CHANGES verdict
+      # sends the builder around again. failOn: never on verify is what keeps
+      # a red test from failing the run before that can happen. max 2 rounds,
+      # then the approver still runs (factory step 5: round 2 done goes to
+      # the approver).
+      until: 'build.status == "READY" && security.verdict == "PASS" && ux.verdict == "PASS" && ui.verdict == "PASS" && code.verdict == "PASS" && verify.exitCode == 0'
+      budget:
+        maxIterations: 2
+      onExhausted: continue
+      concurrency: 4
+      body:
+        # security, ux, ui, code, and verify are later in this body, so on
+        # build they are the previous round. Round 1 leaves them undefined;
+        # the prompt's `.field ||` defaults cover findings and verify text.
+        # Round 1 leaves verify undefined. A verify that ran with exitCode
+        # null was signal-killed, so `verify.exitCode == null` is not labeled
+        # round 1. Exit code 0 still renders as 0.
+        # `{{ security || "x" }}` does not validate.
+        - id: build
+          needs: [input, spec, security, ux, ui, code, verify]
+          agent:
+            model: opus
+            prompt:
+              file: prompts/kiln/build.md
+            schema:
+              inline:
+                type: object
+                additionalProperties: false
+                properties:
+                  summary: { type: string }
+                  status: { type: string, enum: [READY, BLOCKED] }
+                required: [summary, status]
+            tools: [Read, Grep, Glob, Bash, Write, Edit, Skill]
+          produces: build
+
+        - id: verify
+          needs: [input, build]
+          command:
+            run: 'node "${KILN_VERIFY_WRAPPER:?KILN_VERIFY_WRAPPER is empty}"'
+            failOn: never
+            capture: [stdout, stderr, exitCode]
+          produces: verify
+
+        # Build and verify stay in order. These four do not need each other,
+        # so concurrency 4 starts them together. They have no Write or Edit.
+        # Bash stays, because the factory prompts diff with git. Yak warns
+        # that concurrent Bash steps share one cwd. The preambles forbid
+        # re-running tests, builds, and any other write; git and file reads
+        # stay. input is inherited for baseRef; it is not in needs.
+        - id: security
+          needs: [spec, build, verify]
+          agent:
+            model: opus
+            context:
+              inherit: [input]
+            prompt:
+              file: prompts/kiln/security.md
+            schema:
+              inline:
+                type: object
+                additionalProperties: false
+                properties:
+                  verdict: { type: string, enum: [PASS, CHANGES] }
+                  findings: { type: string }
+                required: [verdict, findings]
+            tools: [Read, Grep, Glob, Bash, Skill]
+          produces: security
+
+        - id: ux
+          needs: [spec, build, verify]
+          agent:
+            model: sonnet
+            context:
+              inherit: [input]
+            prompt:
+              file: prompts/kiln/ux.md
+            schema:
+              inline:
+                type: object
+                additionalProperties: false
+                properties:
+                  verdict: { type: string, enum: [PASS, CHANGES] }
+                  findings: { type: string }
+                required: [verdict, findings]
+            tools: [Read, Grep, Glob, Bash, Skill]
+          produces: ux
+
+        - id: ui
+          needs: [spec, build, verify]
+          agent:
+            model: sonnet
+            context:
+              inherit: [input]
+            prompt:
+              file: prompts/kiln/ui.md
+            schema:
+              inline:
+                type: object
+                additionalProperties: false
+                properties:
+                  verdict: { type: string, enum: [PASS, CHANGES] }
+                  findings: { type: string }
+                required: [verdict, findings]
+            tools: [Read, Grep, Glob, Bash, Skill]
+          produces: ui
+
+        - id: code
+          needs: [spec, build, verify]
+          agent:
+            model: sonnet
+            context:
+              inherit: [input]
+            prompt:
+              file: prompts/kiln/code.md
+            schema:
+              inline:
+                type: object
+                additionalProperties: false
+                properties:
+                  verdict: { type: string, enum: [PASS, CHANGES] }
+                  findings: { type: string }
+                required: [verdict, findings]
+            tools: [Read, Grep, Glob, Bash, Skill]
+          produces: code
+    produces: rounds
+
+  - id: approver
+    needs: [input, spec, rounds]
+    agent:
+      model: opus
+      prompt:
+        file: prompts/kiln/approver.md
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            decision: { type: string, enum: [APPROVE, ESCALATE] }
+            reason: { type: string }
+          required: [decision, reason]
+      tools: [Read, Grep, Glob, Bash, Write, Skill]
+    produces: decision
+
+  - id: approve
+    needs: [input, decision]
+    gate:
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            decision: { type: string, enum: [approve, reject] }
+          required: [decision]
+      render:
+        inline: 'Approve "{{input.title}}"? Agent decision: {{decision.decision}}. {{decision.reason}}'
+    produces: approval
+
+  - id: land
+    needs: [input, approval]
+    skipIf: 'approval.decision != "approve"'
+    command:
+      run: 'git add -A && git diff --cached --quiet || git commit -m "kiln: $KILN_TASK_TITLE"'

package/workflows/investigation.yaml

@@ -0,0 +1,67 @@
+# One Kiln investigation, run by yak (@lchase/yak).
+#
+# A spike, probe, or research ticket. The agent explores the worktree and
+# returns a findings document. A person approves or rejects it. There is no
+# build, review, verify, or land step, and Kiln does not open a pull request
+# for this workflow, whatever the repo's deliver mode is.
+#
+# The agent artifact is `findings`: `{ "markdown": "<document>" }`.
+# The document uses these headings, in order:
+#   # Findings: <title>
+#   ## Questions
+#   ## Answers          (each answer includes evidence: file paths and command output)
+#   ## Unconfirmed
+#   ## Implications for dependent tickets
+# On approve, Kiln copies that markdown to `<kilnDir>/findings/<jobId>.md`.
+# A later job that depends on this one receives the file as a
+# `## Findings from <title>` section in the spec yak sees.
+#
+# `adapter: "mock"` reads `test/fixtures/kiln-investigation/explore.json`
+# from the checkout. The gate has no fixture.
+# Prompt paths are rewritten to absolute files under the kiln directory
+# before launch, same as workflows/feature.yaml. This prompt has no factory
+# directive; it is stored as itself.
+name: kiln-investigation
+version: "1"
+inputSchema:
+  inline:
+    type: object
+    additionalProperties: false
+    properties:
+      title: { type: string }
+      spec: { type: string }
+      runNonce: { type: string }
+      baseRef: { type: string }
+    required: [title, spec, runNonce, baseRef]
+steps:
+  - id: explore
+    needs: [input]
+    agent:
+      model: opus
+      prompt:
+        file: prompts/kiln/investigation.md
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            markdown: { type: string, minLength: 1 }
+          required: [markdown]
+      # Bash can run read-only commands. File-editing tools are omitted.
+      # The prompt forbids any command that writes.
+      tools: [Read, Grep, Glob, Bash]
+    produces: findings
+
+  - id: approve
+    needs: [input, findings]
+    gate:
+      schema:
+        inline:
+          type: object
+          additionalProperties: false
+          properties:
+            decision: { type: string, enum: [approve, reject] }
+          required: [decision]
+      render:
+        inline: "Approve findings for \"{{input.title}}\"?\n\n{{findings.markdown}}"
+    produces: approval