@jenga-ai/agent 1.1.0 → 1.2.0

package/skills/publish/scripts/publish_deploy.sh

@@ -15,6 +15,7 @@ DROPLET_PIPELINE_SCRIPT="$SCRIPT_DIR/droplet_pipeline.sh"
 NPM_CI_PIPELINE_SCRIPT="$SCRIPT_DIR/npm_ci_pipeline.sh"
 RUN_GATES_SCRIPT="$SCRIPT_DIR/run_gates.sh"
 GENERATE_RELEASE_NOTES_SCRIPT="$SCRIPT_DIR/generate_release_notes.sh"
+FINALIZE_CHANGELOG_SCRIPT="$SCRIPT_DIR/finalize_changelog.sh"
 SUGGEST_SEMVER_SCRIPT="$SCRIPT_DIR/suggest_semver_bump.sh"
 WRITE_LEDGER_ENTRY_SCRIPT="$SCRIPT_DIR/write_ledger_entry.sh"
 IOS_PIPELINE_SCRIPT="$SCRIPT_DIR/ios_pipeline.sh"
@@ -31,6 +32,7 @@ AUTO_YES=0
 DRY_RUN=0
 BUMP_OVERRIDE=""
 RELEASE_NOTES_PATH=""
+RELEASE_NOTES_BYPASSED=0
 PROMPT_INPUT_FD=0
 NON_INTERACTIVE=0
 TARGET_TYPE=""
@@ -41,7 +43,7 @@ SELECTED_VERSION=""
 usage() {
   cat <<'USAGE'
 Usage: publish_deploy.sh [--target <name>] [--config <path>] [--yes] [--dry-run]
-                         [--minor | --major] [--release-notes <path>]
+                         [--minor | --major] [--notes-file <path>]
 USAGE
 }
 
@@ -290,8 +292,7 @@ generate_release_notes() {
     return 0
   fi
 
-  RELEASE_NOTES_PATH="$(publish_temp_release_notes_path)"
-  local cmd=(bash "$GENERATE_RELEASE_NOTES_SCRIPT" --target "$TARGET_NAME" --output "$RELEASE_NOTES_PATH")
+  local cmd=(bash "$GENERATE_RELEASE_NOTES_SCRIPT" --target "$TARGET_NAME")
   if [[ -n "$LAST_TAG" ]]; then
     cmd+=(--from-tag "$LAST_TAG")
   fi
@@ -299,6 +300,8 @@ generate_release_notes() {
   if ! "${cmd[@]}"; then
     fail_with "$EXIT_ADAPTER_FAILURE" "Failed to generate release notes."
   fi
+
+  RELEASE_NOTES_PATH="$PUBLISH_REPO_ROOT/CHANGELOG.md"
 }
 
 review_release_notes() {
@@ -317,9 +320,18 @@ review_release_notes() {
 
 resolve_selected_version() {
   local current_version suggested_version
-  current_version="$(publish_latest_ledger_version "$HISTORY_FILE" 2>/dev/null || true)"
-  [[ -n "$current_version" ]] || current_version='v0.0.0'
-  current_version="$(publish_normalize_version "$current_version")" || current_version='v0.0.0'
+  # For npm/npm-ci targets, package.json is the authoritative version source.
+  # The ledger may lag behind if a previous publish didn't bump package.json.
+  if [[ "$TARGET_TYPE" == "npm" || "$TARGET_TYPE" == "npm-ci" ]]; then
+    local pkg_version
+    pkg_version="$(jq -r '.version // empty' "$PUBLISH_REPO_ROOT/package.json" 2>/dev/null || true)"
+    current_version="$(publish_normalize_version "$pkg_version" 2>/dev/null)" || current_version=''
+  fi
+  if [[ -z "$current_version" ]]; then
+    current_version="$(publish_latest_ledger_version "$HISTORY_FILE" 2>/dev/null || true)"
+    [[ -n "$current_version" ]] || current_version='v0.0.0'
+    current_version="$(publish_normalize_version "$current_version")" || current_version='v0.0.0'
+  fi
 
   suggested_version="$(bash "$SUGGEST_SEMVER_SCRIPT" --yes "$CONFIG_PATH" | tail -n 1 | tr -d '\r')"
   suggested_version="$(publish_normalize_version "$suggested_version")" || fail_with "$EXIT_ADAPTER_FAILURE" "Unable to determine a suggested version."
@@ -380,7 +392,7 @@ run_adapter_pipeline() {
       cmd=(bash "$NPM_PIPELINE_SCRIPT" "$TARGET_NAME" "$CONFIG_PATH")
       ;;
     npm-ci)
-      cmd=(bash "$NPM_CI_PIPELINE_SCRIPT" --target "$TARGET_NAME" --config "$CONFIG_PATH")
+      cmd=(bash "$NPM_CI_PIPELINE_SCRIPT" --target "$TARGET_NAME" --config "$CONFIG_PATH" --version "$SELECTED_VERSION")
       ;;
     droplet)
       cmd=(bash "$DROPLET_PIPELINE_SCRIPT" --target "$TARGET_NAME" --config "$CONFIG_PATH")
@@ -423,6 +435,22 @@ run_post_gates() {
   return 1
 }
 
+finalize_changelog() {
+  # Skipped on a dry run — the real tag and ledger entry are not created
+  # either (see write_ledger_entry's own --dry-run handling), and
+  # [Unreleased] content from generate_release_notes was still updated
+  # earlier in the flow, just left unstamped.
+  (( DRY_RUN )) && return 0
+  # Skipped when release notes were supplied via the --notes-file bypass
+  # flag: RELEASE_NOTES_PATH then points at an arbitrary user-supplied file
+  # rather than the standing CHANGELOG.md, so there is no [Unreleased]
+  # section of the standing file to finalize.
+  (( RELEASE_NOTES_BYPASSED )) && return 0
+
+  bash "$FINALIZE_CHANGELOG_SCRIPT" "$SELECTED_VERSION" "$RELEASE_NOTES_PATH" \
+    || fail_with "$EXIT_ADAPTER_FAILURE" "Failed to finalize CHANGELOG.md."
+}
+
 write_ledger_entry() {
   local platform_state="$1"
   local cmd=(bash "$WRITE_LEDGER_ENTRY_SCRIPT" "$TARGET_NAME" "$TARGET_TYPE" "$platform_state" "$RELEASE_NOTES_PATH" --version "$SELECTED_VERSION" --config "$CONFIG_PATH")
@@ -483,9 +511,10 @@ parse_args() {
         BUMP_OVERRIDE="major"
         shift
         ;;
-      --release-notes)
+      --notes-file)
         [[ $# -ge 2 ]] || { usage >&2; exit 1; }
         RELEASE_NOTES_PATH="$2"
+        RELEASE_NOTES_BYPASSED=1
         shift 2
         ;;
       --help|-h)
@@ -531,6 +560,7 @@ main() {
     platform_state="dry-run"
   fi
 
+  finalize_changelog
   write_ledger_entry "$platform_state"
   print_manual_steps
 }

package/skills/publish/scripts/run_gates.sh

@@ -245,7 +245,7 @@ resolve_default_command() {
   # fall through to iOS tooling. Missing scripts are announced with a clear
   # informational note (on stderr so it does not pollute the captured
   # command) before the gate is reported as skipped upstream.
-  if [[ "$TARGET_TYPE" == "npm" ]]; then
+  if [[ "$TARGET_TYPE" == "npm" || "$TARGET_TYPE" == "npm-ci" ]]; then
     case "$gate_name" in
       build|test|lint)
         if find_npm_script_in_root "$gate_name"; then
@@ -563,7 +563,7 @@ build_gate_list() {
   local -a mandatory_pre_gates=()
 
   if [[ "$PHASE" == "pre" ]]; then
-    if [[ "$TARGET_TYPE" == "npm" ]]; then
+    if [[ "$TARGET_TYPE" == "npm" || "$TARGET_TYPE" == "npm-ci" ]]; then
       # npm-specific mandatory gates: test, build, lint (per E26_S06_T03).
       mandatory_pre_gates=(test build lint)
     else

package/skills/reconcile/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: reconcile
-description: Reconcile the scrum board with actual implementation state. Cross-checks every task's board status against git history and worktrees, merges orphaned worktree branches, demotes unimplemented "Done" items, promotes secretly-implemented items, and cleans stale entries from todo.md. Use when the board feels out of sync, after a big merge session, when tasks were completed outside the normal workflow, or when todo.md has grown stale. Trigger on phrases like "sync the board", "clean up the board", "reconcile", "board is out of date", "todo is stale", or "check what's really done".
+description: Reconcile the scrum board with actual implementation state. Cross-checks every task's board status against git history and worktrees, merges orphaned worktree branches, demotes unimplemented "Done" items, promotes secretly-implemented items, flags code with no board provenance and offers /uncharted segment for it, and cleans stale entries from todo.md. Use when the board feels out of sync, after a big merge session, when tasks were completed outside the normal workflow, or when todo.md has grown stale. Trigger on phrases like "sync the board", "clean up the board", "reconcile", "board is out of date", "todo is stale", or "check what's really done".
 metadata:
   prefered_agent: scrum-master
 ---
 
 # Reconcile — Board ↔ Code Synchronisation
 
-Walks the full board (epics → stories → tasks), verifies each item's status against what actually exists in git, and fixes any drift. Also cleans `project/todo.md` of entries that are already done.
+Walks the full board (epics → stories → tasks), verifies each item's status against what actually exists in git, and fixes any drift. Also cleans `project/todo.md` of entries that are already done. Then runs the same check in reverse — code that exists with no board item and no EST-tagged commit behind it — and offers `/uncharted segment` for what it finds.
 
 ## Instructions
 
@@ -80,14 +80,126 @@ At the end of Phase 4, if any DoD gaps were found across any stories, include a
 
 **Important:** Gap detection is **report-only**. Do not automatically change the status of any story or epic based on unchecked DoD boxes — surface the gaps so a human can review and decide.
 
-### 5. Clean `project/todo.md`
+### 5. Detect unlinked code (no board provenance)
+Phases 2 and 3 ask "does this board item exist in the code?". This phase asks the inverse —
+**"does this code exist on the board?"** — and finds paths with no Jenga provenance at all.
+
+Run:
+
+```bash
+skills/reconcile/scripts/detect-unlinked-code.sh
+```
+
+It emits a single JSON object and exits `0` whether or not it finds anything; read
+`summary.uncharted_paths` rather than branching on the exit status. All the deterministic work —
+exclusions, the board check, the commit check, grouping — is in the script. Everything below is
+judgement and presentation.
+
+A path is reported as unlinked only when **both** provenance signals are absent: no board file
+references it, **and** no commit naming a board item added it. Either signal alone is provenance,
+so a file created by a `task(...)` commit is not reported even if no board file names it by path.
+Signal B accepts the current EST tags (`epic(...)`, `story(...)`, `task(E##_S##_T##)`) and the two
+older conventions still present in this repo's history (`E04_S01: ...` and
+`feat(train): implement E01_S05 - ...`).
+
+The script reuses the board-linkage check from
+`skills/uncharted/scripts/resolve-segment-target.sh` through its batch interface. Do not
+re-derive linkage yourself, and do not substitute a `grep` over `project/board/` if the script
+fails — a second answer to "is this path on the board" is what that reuse exists to prevent.
+If the script exits non-zero, report the failure in the reconcile report and continue to phase 6.
+
+#### Reading the result
+
+- **`groups[]`** — the actionable findings, sorted by `unlinked_count` descending. Each entry is
+  a directory, not a file, because the useful unit for `/uncharted segment` is a directory or
+  feature. Every group directory has itself been checked against the board, so these are
+  directories with no provenance of their own either. `fully_unlinked: true` means *every*
+  candidate file beneath the directory is unlinked — those are the strongest segment candidates
+  and should be offered first. When `false`, the directory holds a mix and only the listed files
+  are unlinked.
+- **`covered_groups[]`** — files with no provenance of their own that nonetheless sit under a
+  directory the board *does* reference (`directory_linkage.status: "linked"`, with the owning
+  board items in `directory_linkage.items` and the spelling that matched in `matched_as`).
+  **Do not offer `/uncharted segment` for these** — the board already owns that directory and a
+  segment run would duplicate existing items. Mention them in the report as a one-line count so
+  the information is not lost, and move on.
+- **`files`** is capped by `--limit` (default 10); `files_truncated` gives the remainder. The
+  counts are always true totals, so never re-count `files` to report a number.
+- **`not_checked[]`** — **this is a third state, not a quiet synonym for unlinked.** It means the
+  linkage question could not be answered for that path (it is outside the repository, it is the
+  repo root, there is no board directory, or it is a stale index entry that no longer exists on
+  disk). Report these under their own heading with the `reason` shown, and:
+  - **never** describe them as unlinked or add them to the unlinked totals;
+  - **never** include them in the `/uncharted segment` offer.
+
+  A group whose `directory_linkage.status` is `not_checked` is a different case: its *files* were
+  checked and are genuinely unlinked, only the directory verdict is missing. Keep offering it, but
+  say the directory itself could not be verified.
+
+  Saying "no board item references this" about a path we never managed to check is a false
+  claim of a verified absence. If a `not_checked` entry looks like it matters, the follow-up is
+  to investigate that path directly, not to assume the worst about it.
+- **`notices[]`** — surface verbatim in the report if non-empty.
+
+#### The `/uncharted segment` offer
+
+Drive this off **`summary.uncharted_paths`** and `groups[]`, not `unlinked_paths` —
+`unlinked_paths` includes the covered files, which must never be offered.
+(`unlinked_paths` == `uncharted_paths` + `covered_paths`.)
+
+If `summary.uncharted_paths` is `0`, note "no unlinked code found" in the report and continue to
+phase 6. Otherwise present the top groups and offer `/uncharted segment`, using the numbered
+form from `CLAUDE.md`'s Interaction Pattern with the free-text option last:
+
+```
+Found <N> path(s) with no board provenance, in <M> director(y|ies):
+
+  1. <directory>  — <unlinked_count> file(s)<, entire directory if fully_unlinked>
+  2. <directory>  — <unlinked_count> file(s)
+  ...
+
+Neither these files nor their directories are referenced by any board item, and no commit
+naming a board item introduced them. How would you like to handle it?
+1. Run `/uncharted segment <directory>` on <top group> now
+2. Choose a different group to run `/uncharted segment` on
+3. Skip for now — carry on with the rest of the reconcile pass
+4. Other (describe below)
+```
+
+List at most the top 10 groups; if there are more, say how many were not shown.
+
+**This offer is non-blocking.** Declining it — option 3, an unrecognised answer, or no answer at
+all — changes nothing about the rest of the reconcile run. Record the finding in the report and
+**continue to phase 6 regardless**. Detection is report-only in the same way DoD gap detection
+is: never change a board status, create a board item, or modify any file on the strength of this
+phase. If the user picks option 1 or 2, finish the reconcile pass first, then hand off to
+`/uncharted segment` at the end so the board is consistent before new items are written.
+
+### 6. Clean `project/todo.md`
 Walk the todo entries parsed in phase 1:
 
 - **Already-done entries** — if an entry references a task/story/epic whose pre-reconcile status (from the snapshot in phase 1) was already a completed status **and** whose implementation has been confirmed (phase 2), **remove the line entirely** from `project/todo.md`.
 - **Newly-reconciled entries** — entries that were commented out in phase 3 stay as `<!-- RECONCILED: ... -->`.
 - If `project/todo.md` is left with only the header, the format comment, and blank lines, delete the file.
 
-### 6. Print a summary
-Output a reconciliation report using the format in `assets/report_format.md`.
+### 7. Print a summary
+Output a reconciliation report using the format in `assets/report_format.md`, with one
+additional section from phase 5 placed just before `TODO CLEANUP`:
+
+```
+🗺️  UNLINKED CODE (no board item for the files or their directory)
+   📁 <directory>  — <N> file(s)  [entire directory]
+   📁 <directory>  — <N> file(s)
+   Offered `/uncharted segment`: <accepted for <directory> | declined>
+   Covered: <N> file(s) in <M> director(y|ies) already owned by a board item — not offered
+
+❓ NOT CHECKED (board linkage could not be determined — not a finding of unlinked)
+   <path>  — <reason>
+```
+
+Omit `UNLINKED CODE` when `summary.uncharted_paths` is 0, omit its `Covered:` line when
+`summary.covered_paths` is 0, and omit `NOT CHECKED` when
+`not_checked[]` is empty. Keep the two separate: merging them would report paths as unlinked
+that were never actually checked.
 
 If no changes were made, print: `Board and todo.md are in sync — nothing to reconcile. ✅`