agentleFS
samwelmungasamwelmunga/jenga-npm/.claude/skills/j-close-story/SKILL.md

j.close-story

Skill0 starsChanged 24 days agoApache-2.0View on GitHub

Close a story by verifying all tasks are in terminal state, extracting actual diff stats per task, computing scope divergence flags, and writing closure metadata to task frontmatter.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 5 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the guard script:

    line 44
  2. Very specific:

    If it exits with code 0 and prints CLOSEABLE, continue.

    line 50
  3. Distinctive:

    If it exits with code 1, halt and report the blocking tasks to the user.

    line 51
  4. Very specific:

    Read the task's execution_scope from its frontmatter:

    line 96
  5. Very specific:

    If execution_scope is empty or absent, treat it as task (no divergence).

    line 102
  6. Distinctive:

    Run the divergence computation:

    line 104
  7. Distinctive:

    Write the result to task frontmatter:

    line 110
  8. Very specific:

    After all tasks have been updated, run the same static Privatized check against the story's own direct commits (E51_S03_T03) before …

    line 174
  9. Very specific:

    If the script prints PRIVATIZED, it has already written status: Privatized to the story's frontmatter.

    line 187
  10. Very specific:

    If the script prints UNCHANGED, proceed as normal: set the following fields in the story's frontmatter:

    line 193
  11. Very specific:

    Use update-task-frontmatter.sh targeting the story file, or edit directly.

    line 198
  12. Very specific:

    If any task had 0 for both fields, note it as potentially untracked:

    line 213
  13. Very specific:

    If any ticket was overwritten from Publicized to Privatized (a precedence mismatch), note it explicitly and point to the logged …

    line 236
  14. Distinctive:

    If the config was missing or malformed, note that divergence flags were skipped:

    line 265

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

close-story — Close a Story

skills/j-close-story/ is the canonical, hand-edited directory for this skill, per CLAUDE.md's "The Canonical Naming Contract" (the E50 reopening of 2026-09-09, which promoted skills/j-close-story/ from generated twin to sole canonical form). The j- prefix is there for collision safety — a real directory under a distinct name, so a host tool shipping its own same-named built-in command cannot shadow it (Claude Code's native skill resolution is a literal-string, directory-name-based match; see project/documentation/skill-authoring.md's "Invocation Convention").

⚠️ scripts/generate-j-alias.sh was retired by E50_S14 and no longer exists — there is nothing to run. This file was previously generated from a bare skills/close-story/SKILL.md source; E50_S15 deleted that directory. This file is now the sole canonical, hand-edited source for this skill — edit it directly.

Purpose

/close-story <story-id> performs the final closure steps for a story:

  1. Verifies all tasks in the story are in a terminal state (Passed, Passed with remarks, or Done).
  2. Extracts actual git diff --stat metrics for each task from the commit history.
  3. Writes actual_files_changed, actual_lines_delta, and scope_divergence_flag to each task's frontmatter.
  4. Runs a static .publicignore blocklist check (E51_S03_T03) against each task's and the story's own touched files, marking status: Privatized in place of the normal terminal status wherever every touched file is permanently excluded from the public mirror — independent of any /mirror-public run having occurred.
  5. Updates the story's frontmatter status to Done (or Privatized, per step 4) and records date_completed.

Instructions

Step 1 — Verify story is closeable

Run the guard script:

bash "$([ -f skills/j-close-story/scripts/check-story-closeable.sh ] && echo skills/j-close-story/scripts/check-story-closeable.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/check-story-closeable.sh)" <story-id>
  • If it exits with code 0 and prints CLOSEABLE, continue.
  • If it exits with code 1, halt and report the blocking tasks to the user. Do not proceed.

Step 2 — Extract per-task diff stats and compute scope divergence

At the start of this step, read project/configs/scope-thresholds.json to check that it exists and is parseable. If it is missing or malformed, log a warning and continue — divergence flags will be skipped (non-blocking). The compute-scope-divergence.sh script handles this gracefully by always printing false on error.

For each task ID listed in the story's tasks: frontmatter array:

  1. Find the task file at project/board/tasks/<task-id>_*.md.
  2. Extract commit SHA(s) for this task:
    git log --all --no-merges --grep="<task-id>" --pretty=format:"%H" 2>/dev/null
    This matches commits whose message contains the EST task identifier (e.g. E32_S06_T01).
  3. Run per-task diff stat extraction:
    bash "$([ -f skills/j-close-story/scripts/extract-task-diff-stats.sh ] && echo skills/j-close-story/scripts/extract-task-diff-stats.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/extract-task-diff-stats.sh)" <task-id>
    The script outputs:
    actual_files_changed: <N>
    actual_lines_delta: <N>
    Parse these values from stdout.
  4. Write stats to task frontmatter:
    bash "$([ -f skills/j-close-story/scripts/update-task-frontmatter.sh ] && echo skills/j-close-story/scripts/update-task-frontmatter.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/update-task-frontmatter.sh)" \
      "project/board/tasks/<task-id>_*.md" \
      actual_files_changed <N>
    
    bash "$([ -f skills/j-close-story/scripts/update-task-frontmatter.sh ] && echo skills/j-close-story/scripts/update-task-frontmatter.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/update-task-frontmatter.sh)" \
      "project/board/tasks/<task-id>_*.md" \
      actual_lines_delta <N>
  5. Compute and write scope divergence flag:

    Read the task's execution_scope from its frontmatter:

    EXECUTION_SCOPE=$(grep '^execution_scope:' "project/board/tasks/<task-id>_*.md" \
      | head -1 | awk '{print $2}')

    If execution_scope is empty or absent, treat it as task (no divergence).

    Run the divergence computation:

    DIVERGENCE_FLAG=$(bash "$([ -f skills/j-close-story/scripts/compute-scope-divergence.sh ] && echo skills/j-close-story/scripts/compute-scope-divergence.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/compute-scope-divergence.sh)" \
      "<execution_scope>" <actual_files_changed> <actual_lines_delta>)

    Write the result to task frontmatter:

    bash "$([ -f skills/j-close-story/scripts/update-task-frontmatter.sh ] && echo skills/j-close-story/scripts/update-task-frontmatter.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/update-task-frontmatter.sh)" \
      "project/board/tasks/<task-id>_*.md" \
      scope_divergence_flag "$DIVERGENCE_FLAG"

    Track diverging tasks in a running list for the final report (Step 5).

  6. Skip tasks with no matched commits — If actual_files_changed is 0 and actual_lines_delta is 0, it likely means the task predates this feature or uses an untracked commit. Write the 0 values anyway so the field is present but do not treat this as an error. Run divergence computation with 0 0 — this will return false for all scopes.
  7. Run the static Privatized check (E51_S03_T03) — immediately after the frontmatter writes and divergence computation above, check whether this task's own work is permanently excluded from the public mirror:
    bash "$([ -f skills/j-close-story/scripts/check-privatized.sh ] && echo skills/j-close-story/scripts/check-privatized.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/check-privatized.sh)" <task-id> "project/board/tasks/<task-id>_*.md"
    This is a static check (per $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)'s "Static vs. Reactive Status Setting" section) — it derives the task's touched-file list from its own EST-tagged commit history (same technique as Step 2) and tests every file against .publicignore, with no dependency on any /mirror-public run having ever occurred.
    • Prints PRIVATIZED on stdout if every touched file matched the blocklist — the script has already written status: Privatized to the task's frontmatter (superseding whatever status was there, including a contradictory Publicized, in which case the script also logs a publicized_privatized_mismatch event to project/logs/events.json as a single appended JSONL line, never a rewrite; manual writes use the dual-path form of scripts/events-append.sh).
    • Prints UNCHANGED if the task has zero matched commits, only partial blocklist coverage, or is already Privatized — no error, no board write.
    • Track any task that came back PRIVATIZED for the final report (Step 5).

Step 3 — Bundle task attribution

A bundle task is one where a single commit message contains multiple task IDs (e.g. task(E32_S06_T01, E32_S06_T02): ...). In this case:

  • Each task matched by git log --grep will independently resolve to the same commit SHA, and each will receive the full bundle stats as its actual_files_changed and actual_lines_delta values.
  • This is the "full credit" attribution model: each task is credited with the total work of the bundle commit since the individual contribution cannot be mechanically separated.
  • An alternative proportional split (divide total stats by number of tasks in the bundle) is mathematically cleaner but requires detecting the bundle size at query time, which is not supported by the current scripts.
  • The full-credit model is the default. Future work may introduce proportional splitting if telemetry shows significant over-counting in bundle scenarios.

Note for tester: bundle attribution means the sum of actual_lines_delta across tasks may exceed the true total for stories where bundle commits were used.


Step 4 — Update story frontmatter

After all tasks have been updated, run the same static Privatized check against the story's own direct commits (E51_S03_T03) before deciding the story's terminal status:

bash "$([ -f skills/j-close-story/scripts/check-privatized.sh ] && echo skills/j-close-story/scripts/check-privatized.sh || echo node_modules/@jenga-ai/agent/skills/j-close-story/scripts/check-privatized.sh)" <story-id> "project/board/stories/<story-id>_*.md"

Passing the story id (E##_S##) rather than a task id makes the script's anchored-grep commit matching ("<id>([^0-9_]|$)") match only the story's own direct commits (e.g. story(E51_S03): ...) — not its children's, since a story id is a literal string prefix of every one of its own tasks' ids.

  • If the script prints PRIVATIZED, it has already written status: Privatized to the story's frontmatter. Do not also write status: Done — Privatized supersedes Done as the more specific terminal status (a story cannot be both), matching how Merged/Publicized supersede an otherwise-unremarkable closed status on tasks. Still set date_completed: <YYYY-MM-DD> (today's date in UTC).
  • If the script prints UNCHANGED, proceed as normal: set the following fields in the story's frontmatter:
    • status: Done
    • date_completed: <YYYY-MM-DD> (today's date in UTC)

Use update-task-frontmatter.sh targeting the story file, or edit directly.


Step 5 — Report

Print a summary to the user:

Story <story-id> closed.
Tasks updated with actual diff stats:
  <task-id>: files_changed=<N>, lines_delta=<N>, scope_divergence_flag=<true|false>
  ...

If any task had 0 for both fields, note it as potentially untracked:

  <task-id>: files_changed=0, lines_delta=0 (no EST-tagged commit found)

Privatized

Include a "Privatized" note listing any task (from Step 2) or the story itself (from Step 4) that check-privatized.sh marked status: Privatized — every one of its touched files was permanently excluded from the public mirror via .publicignore, independent of any /mirror-public run.

Privatized:
  <task-id>: all touched files matched .publicignore
  ...
Story <story-id>: Privatized (all touched files matched .publicignore) — closed as Privatized, not Done

Or, if none were Privatized:

Privatized: none

If any ticket was overwritten from Publicized to Privatized (a precedence mismatch), note it explicitly and point to the logged publicized_privatized_mismatch event in project/logs/events.json for investigation:

  <id>: WARNING — was Publicized, found fully blocklisted, overwritten to Privatized (see
  project/logs/events.json: publicized_privatized_mismatch)

Scope Divergence

Include a "Scope Divergence" section listing every task whose scope_divergence_flag was set to true. If no tasks diverged, note that explicitly.

Scope Divergence:
  <task-id> [scope=<execution_scope>]: files_changed=<N>, lines_delta=<N> — exceeded threshold
  ...

Or, if none diverged:

Scope Divergence: none

The divergence thresholds applied are those from project/configs/scope-thresholds.json:

  • inline scope: max_files=<inline_max_files>, max_lines=<inline_max_lines>
  • story scope: max_files=<story_max_files>
  • task / epic scope: no threshold (always false)

If the config was missing or malformed, note that divergence flags were skipped:

Scope Divergence: skipped (scope-thresholds.json missing or malformed)

Scripts Reference

ScriptPurpose
scripts/check-story-closeable.sh <story-id>Guard: verify all tasks in terminal state
scripts/extract-diff-stats.sh <story-id>Story-level aggregate diff stats (for story frontmatter)
scripts/extract-task-diff-stats.sh <task-id>Per-task diff stats from EST-tagged commits
scripts/update-task-frontmatter.sh <file> <key> <value>Write/update a YAML field in task or story frontmatter
scripts/compute-scope-divergence.sh <execution_scope> <actual_files_changed> <actual_lines_delta>Compute scope divergence flag: prints true or false
scripts/check-privatized.sh <id> <board-file-path>Static .publicignore membership check (task or story); prints PRIVATIZED (status written) or UNCHANGED — no /mirror-public run required

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.