@xn-intenton-z2a/agentic-lib 7.4.0 → 7.4.2

package/.github/workflows/agentic-lib-init.yml

@@ -27,7 +27,7 @@ on:
       mission-seed:
         type: string
         required: false
-        default: "hamming-distance"
+        default: "6-kyu-understand-hamming-distance"
       mission-text:
         type: string
         required: false
@@ -64,22 +64,26 @@ on:
         description: "Mission seed name (purge only)"
         type: choice
         required: false
-        default: "hamming-distance"
+        default: "6-kyu-understand-hamming-distance"
         options:
-          - hamming-distance
-          - fizz-buzz
-          - roman-numerals
-          - lunar-lander
-          - string-utils
-          - dense-encoding
-          - plot-code-lib
-          - cron-engine
-          - owl-ontology
-          - time-series-lab
-          - c64-emulator
-          - ray-tracer
-          - markdown-compiler
-          - empty
+          - 6-kyu-understand-hamming-distance
+          - 2-dan-create-agi
+          - 5-kyu-create-ascii-face
+          - 1-dan-create-c64-emulator
+          - 4-kyu-apply-cron-engine
+          - 4-kyu-apply-dense-encoding
+          - 7-kyu-understand-fizz-buzz
+          - 8-kyu-remember-hello-world
+          - 4-kyu-analyze-json-schema-diff
+          - 3-kyu-analyze-lunar-lander
+          - 2-kyu-evaluate-markdown-compiler
+          - 3-kyu-evaluate-owl-ontology
+          - 2-kyu-create-plot-code-lib
+          - 1-kyu-create-ray-tracer
+          - 6-kyu-understand-roman-numerals
+          - 5-kyu-apply-string-utils
+          - 3-kyu-evaluate-time-series-lab
+          - 8-kyu-remember-empty
       mission-text:
         description: "Freeform mission text for MISSION.md (overrides mission-seed if provided)"
         type: string
@@ -136,7 +140,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       INIT_MODE: ${{ inputs.mode }}
-      INIT_MISSION_SEED: ${{ inputs.mission-seed || 'hamming-distance' }}
+      INIT_MISSION_SEED: ${{ inputs.mission-seed || '6-kyu-understand-hamming-distance' }}
       INIT_MISSION_TEXT: ${{ inputs.mission-text }}
     steps:
       - uses: actions/checkout@v6
@@ -250,10 +254,10 @@ jobs:
 
             const SCHEDULE_MAP = {
               off: null,
-              weekly: '15 6 * * 1',
-              daily: '15 6 * * *',
-              hourly: '15 * * * *',
-              continuous: '5,15,25,35,45,55 * * * *',
+              weekly: '25 6 * * 1',
+              daily: '25 6 * * *',
+              hourly: '25 * * * *',
+              continuous: '5,25,45 * * * *',
             };
 
             if (fs.existsSync(workflowPath)) {

package/README.md

@@ -243,7 +243,7 @@ All task commands accept these flags:
 | `--dry-run` | off | Show the prompt without calling the Copilot SDK |
 | `--target <path>` | current directory | Target repository to transform |
 | `--model <name>` | `claude-sonnet-4` | Copilot SDK model |
-| `--mission <name>` | hamming-distance | Init with --purge before iterating (iterate only) |
+| `--mission <name>` | 6-kyu-understand-hamming-distance | Init with --purge before iterating (iterate only) |
 | `--timeout <ms>` | 600000 | Session timeout in milliseconds (iterate only) |
 
 ### Example: Full Walkthrough
@@ -303,18 +303,39 @@ The `iterate` command runs a single persistent Copilot SDK session that autonomo
 
 ```bash
 # Init a mission and iterate
-npx @xn-intenton-z2a/agentic-lib iterate --mission hamming-distance --model gpt-5-mini
+npx @xn-intenton-z2a/agentic-lib iterate --mission 6-kyu-understand-hamming-distance --model gpt-5-mini
 
 # Iterate on an existing workspace
 npx @xn-intenton-z2a/agentic-lib iterate --target /path/to/workspace
 
 # With a longer timeout (10 minutes)
-npx @xn-intenton-z2a/agentic-lib iterate --mission fizz-buzz --timeout 600000
+npx @xn-intenton-z2a/agentic-lib iterate --mission 7-kyu-understand-fizz-buzz --timeout 600000
 ```
 
 The session uses SDK hooks for observability (tool call tracking, error recovery) and infinite sessions for context management. The agent drives its own read-write-test loop until the mission is complete or the timeout is reached.
 
-**Available missions:** hamming-distance, fizz-buzz, roman-numerals, string-utils, cron-engine, dense-encoding, markdown-compiler, and more (see `src/seeds/missions/`).
+**Available missions** (see `src/seeds/missions/`). Mission names encode difficulty ([Codewars kyu/dan](https://docs.codewars.com/concepts/kata/)) and cognitive type ([Bloom's taxonomy](https://en.wikipedia.org/wiki/Bloom%27s_taxonomy)):
+
+| Mission | Kyu/Dan | Bloom's | Description |
+|---------|---------|---------|-------------|
+| `8-kyu-remember-empty` | 8 kyu | Remember | Blank template |
+| `8-kyu-remember-hello-world` | 8 kyu | Remember | Hello World |
+| `7-kyu-understand-fizz-buzz` | 7 kyu | Understand | Classic FizzBuzz |
+| `6-kyu-understand-hamming-distance` | 6 kyu | Understand | Hamming distance (strings + bits) |
+| `6-kyu-understand-roman-numerals` | 6 kyu | Understand | Roman numeral conversion |
+| `5-kyu-create-ascii-face` | 5 kyu | Create | ASCII face art |
+| `5-kyu-apply-string-utils` | 5 kyu | Apply | 10 string utility functions |
+| `4-kyu-apply-cron-engine` | 4 kyu | Apply | Cron expression parser |
+| `4-kyu-apply-dense-encoding` | 4 kyu | Apply | Dense binary encoding |
+| `4-kyu-analyze-json-schema-diff` | 4 kyu | Analyze | JSON Schema diff |
+| `3-kyu-analyze-lunar-lander` | 3 kyu | Analyze | Lunar lander simulation |
+| `3-kyu-evaluate-time-series-lab` | 3 kyu | Evaluate | Time series analysis |
+| `3-kyu-evaluate-owl-ontology` | 3 kyu | Evaluate | OWL ontology processor |
+| `2-kyu-evaluate-markdown-compiler` | 2 kyu | Evaluate | Markdown compiler |
+| `2-kyu-create-plot-code-lib` | 2 kyu | Create | Code visualization library |
+| `1-kyu-create-ray-tracer` | 1 kyu | Create | Ray tracer |
+| `1-dan-create-c64-emulator` | 1 dan | Create | C64 emulator |
+| `2-dan-create-agi` | 2 dan | Create | AGI vision |
 
 ### Running Local Benchmarks
 
@@ -338,28 +359,28 @@ source .env
 **Run a benchmark:**
 
 ```bash
-# Quick: hamming-distance with gpt-5-mini (simplest mission, ~1-2 min)
+# Quick: hamming-distance with gpt-5-mini (6 kyu, ~1-2 min)
 npx @xn-intenton-z2a/agentic-lib iterate \
-  --mission hamming-distance --model gpt-5-mini --timeout 300000
+  --mission 6-kyu-understand-hamming-distance --model gpt-5-mini --timeout 300000
 
 # Medium: roman-numerals with claude-sonnet-4
 npx @xn-intenton-z2a/agentic-lib iterate \
-  --mission roman-numerals --model claude-sonnet-4
+  --mission 6-kyu-understand-roman-numerals --model claude-sonnet-4
 
-# Complex: string-utils with gpt-4.1 (10 functions, longer timeout)
+# Complex: string-utils with gpt-4.1 (5 kyu, 10 functions, longer timeout)
 npx @xn-intenton-z2a/agentic-lib iterate \
-  --mission string-utils --model gpt-4.1 --timeout 600000
+  --mission 5-kyu-apply-string-utils --model gpt-4.1 --timeout 600000
 ```
 
 **From a local clone** (development):
 
 ```bash
 # From the agentic-lib directory
-npx . iterate --mission hamming-distance --model gpt-5-mini --target /tmp/bench
+npx . iterate --mission 6-kyu-understand-hamming-distance --model gpt-5-mini --target /tmp/bench
 
 # Or link globally
 npm link
-agentic-lib iterate --mission hamming-distance --model gpt-5-mini --target /tmp/bench
+agentic-lib iterate --mission 6-kyu-understand-hamming-distance --model gpt-5-mini --target /tmp/bench
 ```
 
 **Output:**

package/bin/agentic-lib.js

@@ -63,7 +63,7 @@ Options:
   --reseed             Clear features + activity log (keep source code)
   --dry-run            Show what would be done without making changes
   --target <path>      Target repository (default: current directory)
-  --mission <name>     Mission seed name (default: hamming-distance) [purge only]
+  --mission <name>     Mission seed name (default: 6-kyu-understand-hamming-distance) [purge only]
   --mission-file <path>  Use a custom mission file instead of a built-in seed
   --list-missions      List available built-in mission seeds
   --here               Discover the project and generate a MISSION.md, then iterate
@@ -79,7 +79,7 @@ Examples:
   npx @xn-intenton-z2a/agentic-lib transform
   npx @xn-intenton-z2a/agentic-lib maintain-features --model gpt-5-mini
   npx @xn-intenton-z2a/agentic-lib reset --dry-run
-  npx @xn-intenton-z2a/agentic-lib iterate --mission fizz-buzz
+  npx @xn-intenton-z2a/agentic-lib iterate --mission 7-kyu-understand-fizz-buzz
   npx @xn-intenton-z2a/agentic-lib iterate --mission-file ~/my-mission.md
   npx @xn-intenton-z2a/agentic-lib iterate --here
   npx @xn-intenton-z2a/agentic-lib iterate --list-missions
@@ -107,7 +107,7 @@ const target = resolve(targetPath);
 const modelIdx = flags.indexOf("--model");
 const model = modelIdx >= 0 ? flags[modelIdx + 1] : "claude-sonnet-4";
 const missionIdx = flags.indexOf("--mission");
-const mission = missionIdx >= 0 ? flags[missionIdx + 1] : "hamming-distance";
+const mission = missionIdx >= 0 ? flags[missionIdx + 1] : "6-kyu-understand-hamming-distance";
 const cyclesIdx = flags.indexOf("--cycles");
 const cycles = cyclesIdx >= 0 ? parseInt(flags[cyclesIdx + 1], 10) : 0;
 const stepsIdx = flags.indexOf("--steps");
@@ -277,7 +277,7 @@ async function runIterate() {
     }
     console.log(`\n=== Init with custom mission: ${missionFile} ===\n`);
     execSync(
-      `node ${resolve(pkgRoot, "bin/agentic-lib.js")} init --purge --mission empty --target ${target}`,
+      `node ${resolve(pkgRoot, "bin/agentic-lib.js")} init --purge --mission 8-kyu-remember-empty --target ${target}`,
       { encoding: "utf8", timeout: 60000, stdio: "inherit" },
     );
     // Overwrite MISSION.md with the custom file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.4.0",
+  "version": "7.4.2",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/commit-if-changed/action.yml

@@ -35,8 +35,12 @@ runs:
         fi
         if ! git diff --cached --quiet; then
           git commit -m "${{ inputs.commit-message }}"
+          # Stash any unstaged changes (e.g. log/screenshot files we just unstaged)
+          # so that git pull --rebase can work cleanly
+          git stash 2>/dev/null || true
           REF="${{ inputs.push-ref }}"
           MAX_RETRIES=3
+          PUSH_SUCCESS=""
           REMOTE_REF_EXISTS=""
           if [ -n "$REF" ]; then
             git ls-remote --exit-code origin "$REF" > /dev/null 2>&1 && REMOTE_REF_EXISTS="true"
@@ -53,7 +57,7 @@ runs:
                   continue
                 }
               fi
-              git push origin "$REF" && { REMOTE_REF_EXISTS="true"; break; }
+              git push origin "$REF" && { REMOTE_REF_EXISTS="true"; PUSH_SUCCESS="true"; break; }
             else
               git pull --rebase || {
                 echo "Rebase conflict on attempt $attempt — aborting rebase and retrying"
@@ -61,13 +65,15 @@ runs:
                 sleep $((attempt * 2))
                 continue
               }
-              git push && break
-            fi
-            if [ "$attempt" -eq "$MAX_RETRIES" ]; then
-              echo "::error::Failed to push after $MAX_RETRIES attempts"
-              exit 1
+              git push && { PUSH_SUCCESS="true"; break; }
             fi
             echo "Push failed on attempt $attempt, retrying..."
             sleep $((attempt * 2))
           done
+          # Restore stashed unstaged changes
+          git stash pop 2>/dev/null || true
+          if [ "$PUSH_SUCCESS" != "true" ]; then
+            echo "::error::Failed to push after $MAX_RETRIES attempts"
+            exit 1
+          fi
         fi

package/src/mcp/server.js

@@ -120,7 +120,7 @@ const TOOLS = [
       properties: {
         mission: {
           type: "string",
-          description: "Mission seed name (e.g. 'hamming-distance', 'fizz-buzz')",
+          description: "Mission seed name (e.g. '6-kyu-understand-hamming-distance', '7-kyu-understand-fizz-buzz')",
         },
         profile: {
           type: "string",

package/src/scripts/push-to-logs.sh

@@ -29,6 +29,10 @@ fi
 
 echo "push-to-logs: pushing ${FILES[*]} to ${BRANCH}"
 
+# Mark the workspace as safe (needed in container jobs where the checkout
+# was done by a different user, e.g. Playwright containers)
+git config --global --add safe.directory "$(pwd)" 2>/dev/null || true
+
 # Configure git
 git config --local user.email 'action@github.com'
 git config --local user.name 'GitHub Actions[bot]'
@@ -39,13 +43,21 @@ for f in "${FILES[@]}"; do
   cp "$f" "${TMPDIR}/$(basename "$f")"
 done
 
+# Remember which branch/ref to return to
+ORIGINAL_REF=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+if [ "$ORIGINAL_REF" = "HEAD" ]; then
+  ORIGINAL_REF=$(git rev-parse HEAD 2>/dev/null || echo "")
+fi
+
+# Stash any uncommitted changes so branch switching works cleanly
+git stash --include-untracked 2>/dev/null || true
+
 # Fetch the agentic-lib-logs branch (may not exist yet)
 REMOTE_EXISTS=""
 git fetch origin "${BRANCH}" 2>/dev/null && REMOTE_EXISTS="true" || true
 
 if [ "$REMOTE_EXISTS" = "true" ]; then
-  # Check out existing agentic-lib-logs branch into a detached worktree-like state
-  git checkout "origin/${BRANCH}" -- . 2>/dev/null || true
+  # Check out existing agentic-lib-logs branch
   git checkout -B "${BRANCH}" "origin/${BRANCH}"
 else
   # Create orphan branch
@@ -79,8 +91,15 @@ else
   done
 fi
 
-# Return to previous branch
-git checkout - 2>/dev/null || git checkout main 2>/dev/null || true
+# Return to original branch/ref
+if [ -n "$ORIGINAL_REF" ]; then
+  git checkout "$ORIGINAL_REF" 2>/dev/null || git checkout main 2>/dev/null || true
+else
+  git checkout main 2>/dev/null || true
+fi
+
+# Restore stashed changes
+git stash pop 2>/dev/null || true
 
 # Clean up
 rm -rf "$TMPDIR"

package/src/seeds/missions/2-dan-create-agi.md

@@ -0,0 +1,22 @@
+# Mission
+
+**Agentic-lib** is evolving into an intelligent automation system endowed with multiple AGI-aligned capabilities, all oriented toward a coherent long-term purpose: enabling agentic, cross-repository intelligent automation. The ultimate vision is a network of self-managing coding agents that can understand high-level goals, break them down, execute tasks across many projects, learn from their experiences, and seek assistance when needed – all with minimal human intervention. Each of the new features (Memory, Planning, Goal Decomposition, Self-Improvement, Replication, and Help-Seeking) contributes to this vision in a concrete, feasible way, building the stepping stones toward a truly autonomous development workflow.
+
+In the near term, these traits function as enhancements to the JavaScript CLI/Lambda agent that drives **agentic-lib**:
+- **Memory** provides continuity. The agent now retains a log of actions and outcomes, which means it can carry context from one step to the next. This is immediately useful for avoiding redundant operations and will later allow experience-based learning. For example, when the agent works on Repository A and then on Repository B, a memory of patterns or solutions from A could inform its actions on B.
+- **Planning** gives the agent foresight. Instead of reacting to one command at a time, it can map out a sequence of tasks to achieve a bigger objective. Right now it executes those plans instantly, but this capability will expand to planning over longer durations (even across workflow runs) and coordinating complex changes (like a multi-step refactor that touches many parts of a codebase or multiple repositories).
+- **Goal Decomposition** adds transparency and manageability to complex objectives. The agent can articulate a game plan (a set of sub-tasks) for a broad goal, which can be reviewed or assigned out. In a multi-repository scenario, the agent might decompose a company-wide objective into repo-specific tasks. This structured breakdown makes large-scale automation safer and more organized, since each piece can be tracked (potentially as separate issues or pull requests).
+- **Self-Improvement** makes the agent reflective. By tracking its performance (how many errors, how fast it completes tasks) the agent lays the groundwork for optimizing itself. In the short run, this means better observability and diagnostics in the system. In the long run, the agent could use this information to autonomously fine-tune its own algorithms – for instance, detecting that it often fails a certain kind of task and adjusting its approach or updating its code. This trait keeps the agent aligned with best practices and efficiency as it scales up.
+- **Replication** unlocks scale. The agent is no longer a singleton processing one item at a time – it can replicate its effort either through parallel processing or by spawning new agent instances. Immediately, this manifests as parallel command execution which speeds up workflows (e.g., running multiple checks or updates simultaneously). Looking forward, replication means the agentic-lib model can be instantiated in multiple environments at once: think of dozens of agent clones each working on a different repository but sharing the same core knowledge. This horizontal scaling is essential for cross-repository automation in large organizations.
+- **Help-Seeking** keeps the agent humble and effective. When the agent encounters something it doesn’t know, it can ask an external AI or resource, rather than stalling or guessing wrongly. Currently, this is achieved via OpenAI API calls for answers. As this feature matures, the agent will integrate more sources (documentation, human feedback) and become increasingly adept at knowing when and how to seek help. This ensures that as the agent’s autonomy grows, it remains grounded and correct in its actions, leveraging the broader world’s knowledge.
+
+All these capabilities align to serve a **unified mission**: an autonomous system that can handle the lifecycle of software development tasks across multiple projects. Concretely, we are moving toward a scenario where you could give the agent a high-level directive (for example, “ensure all our repositories are using the latest version of library X and adhere to security policy Y”), and the agent would:
+1. **Understand and Plan:** It would use Goal Decomposition and Planning to figure out what needs to be done for each repository – maybe creating a checklist per repository.
+2. **Take Action in Parallel:** Using Replication, it would initiate changes in multiple repositories at once (branching, editing files, running tests), using memory to avoid repeating known fixes and using its plan as a guide.
+3. **Learn and Adapt:** Throughout, Self-Improvement metrics would monitor which repos encountered issues (maybe some tests failed or some had edge cases). The agent could adjust its approach repository by repository – for instance, if it learned a better fix in one place, Memory would carry that knowledge to the others.
+4. **Seek Guidance if Stuck:** If a particular repository has an unusual setup that the agent doesn’t understand, the Help-Seeking trait would kick in – the agent might query documentation or even open a “help needed” issue for a human maintainer, ensuring that it doesn’t silently fail.
+5. **Deliver Results:** Finally, the agent would open pull requests or issues summarizing changes for each repository (or automatically merge them if permitted), effectively executing a coordinated cross-repo update with minimal human oversight.
+
+The long-term purpose is ambitious but grounded in these tangible capabilities. Each new feature is a **plausible next step**: for example, after implementing basic memory, the next step is to make that memory persistent or sharable among agent instances (so that one agent’s learnings become every agent’s knowledge). After introducing planning and decomposition, the next step is to integrate those with the GitHub issue workflow – the agent could start creating and managing issues on its own to track sub-tasks. Self-improvement opens the door to techniques like on-the-fly model prompting (the agent asking “how can I do this better?” and applying the advice). Replication will eventually entail deploying the agent as a service or container that can be instantiated on demand for whatever project needs it. And help-seeking will evolve into a rich web of integrations with documentation, Q&A forums, and direct human loop-ins when necessary.
+
+In summary, the trajectory defined in this feature set steers **agentic-lib** toward becoming a general-purpose automation AI for software projects. It’s not science fiction – each step is achievable with incremental improvements and integrations, and together they compound into a system that can handle increasing complexity. By focusing on feasible enhancements now (like logging memory, adding parallelism, using an API for help, etc.), we ensure that future leaps (like autonomous multi-repo refactoring or self-directed learning) are built on solid ground. All traits work in concert: memory and help-seeking ensure it has the knowledge, planning and decomposition give it strategy, replication gives it manpower, and self-improvement ensures it keeps getting better. With these aligned, **agentic-lib** can truly fulfill its mission of agentic, cross-repository intelligent automation – a stepping stone toward the broader vision of self-evolving code.

package/src/seeds/missions/4-kyu-analyze-json-schema-diff.md

@@ -0,0 +1,4 @@
+# Mission
+
+**json‑schema‑diff** is designed to help API developers and teams track and validate changes in JSON Schemas. 
+By providing a human‑readable diff, the tool simplifies the evolution of API definitions and facilitates collaboration during version upgrades.

package/src/seeds/missions/5-kyu-create-ascii-face.md

@@ -0,0 +1,4 @@
+# Mission
+
+Create a CLI app that depicts emotion using facial expressions using ascii art.
+This will be the emotion communication mechanism for an AI.

package/src/seeds/missions/8-kyu-remember-hello-world.md

@@ -0,0 +1,3 @@
+# Mission
+
+Deliver the traditional first program to write in a new language, the "Hello World!" message.

package/src/seeds/zero-package.json

@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.4.0"
+    "@xn-intenton-z2a/agentic-lib": "^7.4.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

package/src/seeds/zero-MISSION-empty.md

@@ -1,3 +0,0 @@
-# Mission
-
-Describe your project's mission here. The agentic workflows will evolve `src/lib/main.js` to fulfil this mission.