@kody-ade/kody-engine 0.4.19 → 0.4.21

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
@@ -273,6 +335,16 @@ ensure_label "$failed_label" "b60205" "kody goal-runner: task failed; needs huma
 # counting child tasks, so list_goal_issues can filter it out cleanly.
 ensure_goal_issue
 
+# Open the draft goal PR if the goal branch already exists. Must run BEFORE
+# any of the early exits below (in_flight check, no-undispatched-task idle,
+# etc.) — otherwise active goals that always have a task in flight would
+# never get past the in_flight gate to reach the late call site, leaving
+# the umbrella row without its branch + preview anchor in the dashboard.
+# `ensure_goal_pr` is a safe no-op when the branch hasn't been created yet
+# (the lazy-branch-creation block at the dispatch site handles that case;
+# the next tick picks up the PR creation here).
+ensure_goal_pr
+
 # Merge ready goal-task PRs into the goal branch. We own the merge here
 # instead of relying on GitHub's `--auto` flag (which requires the repo's
 # "Allow auto-merge" setting and silently no-ops when disabled). Only merge
@@ -348,31 +420,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"
@@ -469,6 +553,8 @@ else
     fi
   fi
 fi
+# (`ensure_goal_pr` runs at the top of the active path so it's reached even
+# when this tick exits early via the in_flight gate; not duplicated here.)
 
 echo "[goal-tick] dispatching @kody on task #$next_issue (--base $goal_branch)"
 gh issue comment "$next_issue" --body "@kody --base ${goal_branch}"

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,89 @@
+---
+every: 7d
+---
+
+# 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).
+>
+> Cadence is enforced by the engine via the `every: 7d` frontmatter — this
+> file only fires once per 7 days regardless of how often `job-scheduler`
+> wakes. No prose cadence guard needed.
+
+## 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.
+
+### 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`: always `"idle"` — this job has no phases; each fire is a
+one-shot report write.
+
+`data`:
+
+- `lastStaleCount` (number) — how many stale PRs were in the most recent
+  report. Diagnostic only; the engine ignores it.
+
+(Engine-managed fields like `lastFiredAt` live under `data` automatically;
+do not write or rely on them from the prompt.)
+
+`done`: always `false` — this job is evergreen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "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": []
-  }
-}