@kody-ade/kody-engine 0.4.18 → 0.4.20

package/dist/executables/fix/profile.json

@@ -73,7 +73,7 @@
       { "script": "loadTaskState" },
       { "script": "loadConventions" },
       { "script": "loadPriorArt" },
-      { "script": "loadVaultContext" },
+      { "script": "loadMemoryContext" },
       { "script": "loadCoverageRules" },
       { "script": "composePrompt" }
     ],

package/dist/executables/fix/prompt.md

@@ -21,7 +21,7 @@ You are Kody, an autonomous engineer. Apply the feedback below to the existing P
 
 If a prior-art block is present above, scan it before editing — those are earlier attempts (possibly by you, possibly by a human) at the same fix. Note what was rejected and why; do not repeat a discarded approach.
 
-{{vaultContext}}
+{{memoryContext}}
 
 # Required steps
 1. **Extract** every actionable item from the feedback. A structured review uses headings like `### Concerns`, `### Suggestions`, and `### Bugs`; each bullet under those headings is a distinct item. `### Strengths`, `### Summary`, and `### Bottom line` are NOT items — skip them. If the feedback has no headings (plain inline feedback), treat the whole feedback as one item.

package/dist/executables/goal-tick/tick.sh

@@ -196,6 +196,68 @@ with open(path, "w") as f:
 PY
 }
 
+ensure_goal_pr() {
+  # Open a draft goal PR (`goal-<id>` → default branch) early in the goal's
+  # life so the dashboard has a single anchor that ties together the umbrella
+  # issue, the goal branch, and the Vercel preview deploy. Without this PR,
+  # the umbrella issue is just a label-tagged issue with no link to its
+  # branch, so the dashboard can't surface preview/CI/branch on the umbrella
+  # row.
+  #
+  # Lifecycle:
+  #   - Created here as DRAFT on every active tick once origin/<goal_branch>
+  #     exists. Body carries `Closes #<umbrellaNumber>` so the umbrella
+  #     auto-closes on merge.
+  #   - Promoted to ready-for-review by the finalize path when all child
+  #     tasks close (see below).
+  #
+  # Lookup order:
+  #   1. state.json `goalPrUrl` — fast path; skip if already populated.
+  #   2. `gh pr list --head <goal_branch>` — recovery path when state.json
+  #      lost the field (e.g. older goals from before this change).
+  #   3. Create a fresh draft PR.
+  local existing_url existing_num
+  existing_url=$(read_state_field "goalPrUrl")
+  if [ -n "$existing_url" ]; then
+    return 0
+  fi
+
+  # Goal branch must exist on origin before we can open a PR.
+  if ! git ls-remote --exit-code --heads origin "$goal_branch" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Recovery: PR may already exist from a prior tick that didn't persist the
+  # URL. Match by head ref.
+  existing_num=$(gh pr list --head "$goal_branch" --state open --json number --jq '.[0].number // empty' 2>/dev/null || echo "")
+  if [ -n "$existing_num" ] && [[ "$existing_num" =~ ^[0-9]+$ ]]; then
+    existing_url=$(gh pr view "$existing_num" --json url --jq .url 2>/dev/null || echo "")
+  else
+    local title body goal_issue_number
+    title="goal: ${goal_id}"
+    goal_issue_number=$(read_state_field "goalIssueNumber")
+    if [ -n "$goal_issue_number" ] && [ "$goal_issue_number" != "0" ]; then
+      body=$(printf "Tracking integration PR for goal **%s**.\n\nChild task PRs merge into \`%s\`. This PR is held in **draft** until every task is complete, then promoted to ready-for-review by goal-tick.\n\nCloses #%s\n" "$goal_id" "$goal_branch" "$goal_issue_number")
+    else
+      body=$(printf "Tracking integration PR for goal **%s**.\n\nChild task PRs merge into \`%s\`. Held in **draft** until every task is complete.\n" "$goal_id" "$goal_branch")
+    fi
+    existing_url=$(gh pr create \
+      --draft \
+      --head "$goal_branch" \
+      --base "$default_branch" \
+      --title "$title" \
+      --body "$body" 2>/dev/null || echo "")
+    if [ -z "$existing_url" ]; then
+      echo "[goal-tick] ensure_goal_pr: gh pr create failed (continuing without goal PR)"
+      return 0
+    fi
+    echo "[goal-tick] opened draft goal PR ${existing_url} for ${goal_id}"
+  fi
+
+  # Persist URL into state.json so subsequent ticks skip the lookup.
+  set_state_field "goalPrUrl" "$existing_url"
+}
+
 list_goal_issues() {
   # Up to 100 goal-labelled issues. PRs filtered out. Also filters out the
   # umbrella goal issue (if any) — it shares the `goal:<id>` label so the
@@ -348,31 +410,43 @@ open_count=$(echo "$issues_json" | python3 -c "import json,sys; print(sum(1 for
 if [ "$open_count" = "0" ]; then
   echo "[goal-tick] all $total task(s) closed — finalising goal"
 
-  # Open the goal PR if it doesn't already exist. We only care about origin/<goal_branch>:
-  # the goal branch should exist (created by goal-scheduler). If not, log and skip
-  # PR creation but still mark state=done so the goal moves out of `active`.
+  # Promote (or open) the goal PR. The active path opens this PR as a draft
+  # once the goal branch exists, so by finalize it almost always already
+  # exists — we just mark it ready-for-review and refresh the body. Older
+  # goals from before the early-PR change may still need first-time creation
+  # here as a fallback.
   goal_pr_url=""
   if git ls-remote --exit-code --heads origin "$goal_branch" >/dev/null 2>&1; then
-    existing_pr=$(gh pr list --head "$goal_branch" --state open --json number,url --jq '.[0]' 2>/dev/null || echo "")
+    existing_pr=$(gh pr list --head "$goal_branch" --state open --json number,url,isDraft --jq '.[0]' 2>/dev/null || echo "")
+    title="goal: ${goal_id}"
+    goal_issue_number=$(read_state_field "goalIssueNumber")
+    # `Closes #N` auto-closes the umbrella goal issue on PR merge — that's
+    # how the dashboard learns the goal is done. Skip the line gracefully
+    # if no umbrella issue was ever opened (older goals from before this
+    # change, or `gh issue create` failed silently during a tick).
+    if [ -n "$goal_issue_number" ] && [ "$goal_issue_number" != "0" ]; then
+      body=$(printf "Final integration PR for goal **%s**.\n\nAll task issues are closed and merged into \`%s\`. Ready for review.\n\nCloses #%s\n" "$goal_id" "$goal_branch" "$goal_issue_number")
+    else
+      body=$(printf "Final integration PR for goal **%s**.\n\nAll task issues are closed and merged into \`%s\`. Ready for review.\n" "$goal_id" "$goal_branch")
+    fi
     if [ -z "$existing_pr" ] || [ "$existing_pr" = "null" ]; then
-      title="goal: ${goal_id}"
-      goal_issue_number=$(read_state_field "goalIssueNumber")
-      # `Closes #N` auto-closes the umbrella goal issue on PR merge — that's
-      # how the dashboard learns the goal is done. Skip the line gracefully
-      # if no umbrella issue was ever opened (older goals from before this
-      # change, or `gh issue create` failed silently during a tick).
-      if [ -n "$goal_issue_number" ] && [ "$goal_issue_number" != "0" ]; then
-        body=$(printf "Final integration PR for goal **%s**.\n\nAll task issues are closed and merged into \`%s\`. Ready for review.\n\nCloses #%s\n" "$goal_id" "$goal_branch" "$goal_issue_number")
-      else
-        body=$(printf "Final integration PR for goal **%s**.\n\nAll task issues are closed and merged into \`%s\`. Ready for review.\n" "$goal_id" "$goal_branch")
-      fi
       goal_pr_url=$(gh pr create \
         --head "$goal_branch" \
         --base "$default_branch" \
         --title "$title" \
         --body "$body" 2>/dev/null || echo "")
     else
+      existing_num=$(echo "$existing_pr" | python3 -c "import json,sys; print(json.load(sys.stdin).get('number',''))")
       goal_pr_url=$(echo "$existing_pr" | python3 -c "import json,sys; print(json.load(sys.stdin).get('url',''))")
+      is_draft=$(echo "$existing_pr" | python3 -c "import json,sys; print('true' if json.load(sys.stdin).get('isDraft') else 'false')")
+      # Refresh the body with the finalize copy so reviewers see the right
+      # framing. Best-effort — failure is non-fatal.
+      gh pr edit "$existing_num" --body "$body" >/dev/null 2>&1 || true
+      if [ "$is_draft" = "true" ]; then
+        echo "[goal-tick] promoting draft goal PR #${existing_num} to ready-for-review"
+        gh pr ready "$existing_num" >/dev/null 2>&1 \
+          || echo "[goal-tick] failed to mark PR #${existing_num} ready (continuing)"
+      fi
     fi
   else
     echo "[goal-tick] goal branch ${goal_branch} not found on origin — skipping final PR"
@@ -470,6 +544,11 @@ else
   fi
 fi
 
+# Open the draft goal PR now that the branch exists. The PR is the dashboard's
+# single anchor for the goal's branch + preview + CI; finalize promotes it
+# from draft to ready-for-review when every task has closed.
+ensure_goal_pr
+
 echo "[goal-tick] dispatching @kody on task #$next_issue (--base $goal_branch)"
 gh issue comment "$next_issue" --body "@kody --base ${goal_branch}"
 gh issue edit "$next_issue" --add-label "$dispatched_label"

package/dist/executables/job-tick/prompt.md

@@ -47,8 +47,19 @@ If you fail to emit this block, or the JSON is invalid, the tick fails and the g
 ## Rules
 
 - Never edit, create, or delete files in the working tree.
-- Never commit or push.
+- Never commit or push via `git`. The only permitted commit path is `gh api -X PUT` against the report file (see exception below).
 - Only shell calls allowed: `gh`. Everything must go through it.
 - Keep each tick focused: do one action per candidate per wake. The cron will call you again.
 - If state says you're waiting on something, just check and re-emit — don't spawn a duplicate.
 - Honour the job body's `## Restrictions` over any inferred shortcut.
+
+### Single permitted write: the job's report file
+
+A job MAY (optionally — only if its body asks for it) write a single
+markdown report file at the canonical path:
+
+```
+.kody/reports/{{jobSlug}}.md
+```
+
+Only that exact path. Only via `gh api -X PUT /repos/<owner>/<repo>/contents/.kody/reports/{{jobSlug}}.md` (with base64 content + `sha` of the existing file when updating). All other writes — code files, other report paths, other slugs — remain forbidden. The dashboard's `/reports` page surfaces these files automatically; this is the canonical channel for a job's diagnostic output when an issue comment isn't expressive enough.

package/dist/executables/resolve/profile.json

@@ -64,7 +64,7 @@
         "script": "loadConventions"
       },
       {
-        "script": "loadVaultContext"
+        "script": "loadMemoryContext"
       },
       {
         "script": "loadCoverageRules"

package/dist/executables/resolve/prompt.md

@@ -9,7 +9,7 @@ You are Kody, an autonomous engineer. A `git merge origin/{{baseBranch}}` into P
 
 {{conflictedFiles}}
 
-{{preferBlock}}{{conventionsBlock}}{{vaultContext}}{{toolsUsage}}# Working-tree conflict markers (truncated)
+{{preferBlock}}{{conventionsBlock}}{{memoryContext}}{{toolsUsage}}# Working-tree conflict markers (truncated)
 
 {{conflictMarkersPreview}}
 

package/dist/executables/run/profile.json

@@ -53,7 +53,7 @@
       { "script": "loadTaskState" },
       { "script": "resolveArtifacts" },
       { "script": "loadPriorArt" },
-      { "script": "loadVaultContext" },
+      { "script": "loadMemoryContext" },
       { "script": "loadConventions" },
       { "script": "loadCoverageRules" },
       { "script": "composePrompt" }

package/dist/executables/run/prompt.md

@@ -25,7 +25,7 @@ If the plan above is non-empty, TREAT IT AS AUTHORITATIVE — follow its file li
 
 If a prior-art block is present above, READ THE DIFFS — those are failed or superseded attempts at this same issue. Identify what went wrong (review comments, the fact they were closed without merging, or behavioural gaps in the diff itself) and pick a different approach. Repeating a prior failed attempt is a hard failure even if your tests pass locally.
 
-{{vaultContext}}
+{{memoryContext}}
 
 # Required steps (all in this one session — no handoff)
 1. **Research** — read the issue carefully, then meet the research floor below before any Edit/Write. Use Grep/Glob/Read to investigate.

package/dist/jobs/watch-stale-prs.md

@@ -0,0 +1,86 @@
+# watch-stale-prs
+
+> Weekly digest of open PRs that haven't been touched in a while. Writes a
+> markdown report at `.kody/reports/watch-stale-prs.md` (surfaced by the
+> dashboard's `/reports` page).
+
+## Job
+
+Find every open PR untouched for **≥ 7 days** and write a report listing
+them, sorted by staleness (oldest first). When there are no stale PRs,
+write a short "all clear" report so operators know the check ran.
+
+**Cadence guard.** Skip this tick unless `data.lastRunAt` is null or older
+than 7 days from now. When skipping, emit the same state back unchanged
+with no `gh` calls.
+
+### What "stale" means
+
+A PR is stale if:
+
+- `state` is `OPEN`, AND
+- `updatedAt` is more than 7 days before now.
+
+Use `gh pr list --state open --limit 100 --json number,title,url,updatedAt,author`
+to enumerate. Filter and sort client-side; do not call `gh` once per PR.
+
+### Report shape
+
+Write to `.kody/reports/watch-stale-prs.md`. Overwrite each run.
+
+When stale PRs exist:
+
+```markdown
+# Stale PRs — <ISO date>
+
+🟡 <N> PR(s) untouched for > 7 days.
+
+| # | Title | Author | Days stale | Updated |
+|---|-------|--------|------------|---------|
+| [#123](url) | <title> | @user | 14 | 2026-04-25 |
+| ... | | | | |
+```
+
+When none:
+
+```markdown
+# Stale PRs — <ISO date>
+
+🟢 No open PRs untouched for more than 7 days.
+```
+
+Truncate to the 50 oldest if the list is longer; append a final line
+`> … and N more not shown`.
+
+## Allowed Commands
+
+- `gh pr list --state open --limit 100 --json number,title,url,updatedAt,author`
+- `gh api -X GET /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md`
+  — only to fetch the existing file's `sha` for an update.
+- `gh api -X PUT /repos/{owner}/{repo}/contents/.kody/reports/watch-stale-prs.md`
+  — to write the report (base64-encoded `content`, `message`, and `sha`
+  when updating). This is the **only** permitted write path for this job.
+
+## Restrictions
+
+- Never edit, create, or delete any other file in the working tree.
+- Never `git commit`, `git push`, or open a PR.
+- Never post comments on PRs or issues; the report file is the only
+  output channel.
+- Never call `gh` per-PR — one `pr list` is enough.
+
+## State
+
+`cursor`:
+
+- `"idle"` — between runs (cadence guard skipped this tick or the run
+  finished cleanly).
+
+`data`:
+
+- `lastRunAt` (string, ISO) — when the report was last written. Used by
+  the cadence guard.
+- `lastStaleCount` (number) — how many stale PRs were in the most recent
+  report. Diagnostic only.
+
+`done`: always `false` — this job is evergreen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,18 @@
     "templates",
     "kody.config.schema.json"
   ],
+  "scripts": {
+    "kody": "tsx bin/kody.ts",
+    "build": "tsup && node scripts/copy-assets.cjs",
+    "test": "vitest run tests/unit tests/int --no-coverage",
+    "test:e2e": "vitest run tests/e2e --no-coverage",
+    "test:all": "vitest run tests --no-coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "prepublishOnly": "pnpm build"
+  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119"
@@ -32,16 +44,5 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
-  "scripts": {
-    "kody": "tsx bin/kody.ts",
-    "build": "tsup && node scripts/copy-assets.cjs",
-    "test": "vitest run tests/unit tests/int --no-coverage",
-    "test:e2e": "vitest run tests/e2e --no-coverage",
-    "test:all": "vitest run tests --no-coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write"
-  }
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
+}

package/dist/executables/memorize/profile.json

@@ -1,48 +0,0 @@
-{
-  "name": "memorize",
-  "role": "watch",
-  "describe": "Scheduled: synthesize recently merged PRs into the project's .kody/vault/ markdown wiki and open a PR with the changes.",
-  "kind": "scheduled",
-  "schedule": "0 3 * * *",
-  "inputs": [],
-  "claudeCode": {
-    "model": "inherit",
-    "permissionMode": "acceptEdits",
-    "maxTurns": null,
-    "maxThinkingTokens": null,
-    "systemPromptAppend": null,
-    "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
-    "hooks": ["block-git"],
-    "skills": [],
-    "commands": [],
-    "subagents": [],
-    "plugins": [],
-    "mcpServers": []
-  },
-  "cliTools": [
-    {
-      "name": "gh",
-      "install": {
-        "required": true,
-        "checkCommand": "command -v gh"
-      },
-      "verify": "gh auth status",
-      "usage": "Use `gh` only for read-only inspection (`gh pr view`, `gh pr list`, `gh api`) when you need extra context on a referenced PR. Never use it to commit, push, or open PRs — the wrapper does that.",
-      "allowedUses": ["pr", "api", "issue"]
-    }
-  ],
-  "inputArtifacts": [],
-  "outputArtifacts": [],
-  "scripts": {
-    "preflight": [
-      { "script": "memorizeFlow" },
-      { "script": "composePrompt" }
-    ],
-    "postflight": [
-      { "script": "parseAgentResult" },
-      { "script": "abortUnfinishedGitOps" },
-      { "script": "commitAndPush" },
-      { "script": "ensureMemorizePr" }
-    ]
-  }
-}

package/dist/executables/memorize/prompt.md

@@ -1,59 +0,0 @@
-You are **kody memorize**, the project's long-term memory keeper. You synthesize recently merged work into a markdown knowledge base at `.kody/vault/` so future kody runs can recall decisions, conventions, and component knowledge.
-
-## What you have
-
-### Recent merged PRs (since {{vaultSinceIso}})
-
-{{recentPrs}}
-
-### Existing vault index
-
-Vault root: `.kody/vault/`
-
-{{vaultIndex}}
-
-## What to do
-
-1. **Read each recent PR's title, body, and (if useful) diff via `gh pr view <n>` / `gh pr diff <n>`.**
-2. **Map each PR to the concept pages it affects** — files like `architecture/<area>.md`, `conventions/<topic>.md`, `decisions/<slug>.md`, `components/<name>.md`, or whatever organization the existing vault uses. If the vault is empty, start with a small set of pages reflecting what you actually learned.
-3. **Update or create those pages.** Each page is a concept (e.g. "executor", "release flow"), NOT a per-PR log. A PR contributes one or more updates — small additions, edits to keep current, links back to the PR URL.
-4. **Cross-link** related pages with relative markdown links so the vault forms a connected graph.
-5. **Be terse.** Each page is reference material, not a story. One short paragraph per fact, bullet lists where useful, links instead of recapping.
-6. **Don't duplicate the codebase.** Capture *what was decided* and *why*, not *how* the code looks — the code is authoritative for that.
-7. **Don't invent.** If a PR's intent isn't clear, skip it rather than guessing.
-
-## Page conventions
-
-- Filename: `kebab-case.md`.
-- Frontmatter (YAML) on every page:
-  ```yaml
-  ---
-  title: <Human Title>
-  type: architecture | convention | decision | component | runbook
-  updated: {{vaultUpdatedIso}}
-  sources:
-    - <PR URL or file path>
-  ---
-  ```
-- Body: one short intro paragraph, then sections.
-- Cross-references via relative links: `[executor](../architecture/executor.md)`.
-
-## Rules
-
-- Edit files only under `.kody/vault/`. Do not touch any other path.
-- Do not commit or push. The wrapper does it.
-- Do not run `git` or `gh` for anything except read-only inspection of referenced PRs.
-- If there is nothing meaningful to add (PRs are trivial chores, all already captured, etc.), say so and emit `DONE` with `COMMIT_MSG: chore(vault): no updates`. The wrapper will detect no changes and skip the PR.
-
-## Output contract (MANDATORY)
-
-End your response with these lines, exactly:
-
-```
-DONE
-COMMIT_MSG: chore(vault): <one-line summary>
-PR_SUMMARY:
-<2–6 line summary of what changed in the vault and why>
-```
-
-If you decide to abort with no changes, emit `DONE` with the no-updates `COMMIT_MSG` and a brief `PR_SUMMARY` saying so.

package/dist/executables/watch-stale-prs/profile.json

@@ -1,30 +0,0 @@
-{
-  "name": "watch-stale-prs",
-  "role": "watch",
-  "describe": "Scheduled: list open PRs untouched for N days and report. No agent invocation.",
-  "kind": "scheduled",
-  "schedule": "0 8 * * MON",
-  "inputs": [],
-  "claudeCode": {
-    "model": "inherit",
-    "permissionMode": "default",
-    "maxTurns": null,
-    "systemPromptAppend": null,
-    "tools": [],
-    "hooks": [],
-    "skills": [],
-    "commands": [],
-    "subagents": [],
-    "plugins": [],
-    "mcpServers": []
-  },
-  "cliTools": [],
-  "scripts": {
-    "preflight": [
-      {
-        "script": "watchStalePrsFlow"
-      }
-    ],
-    "postflight": []
-  }
-}