@xn-intenton-z2a/agentic-lib 7.1.61 → 7.1.62

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

@@ -90,11 +90,11 @@ jobs:
       action: ${{ steps.respond.outputs.action }}
       action-arg: ${{ steps.respond.outputs.action-arg }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -106,9 +106,32 @@ jobs:
         working-directory: .github/agentic-lib/actions/agentic-step
         run: npm ci
 
+      - name: Read test command from config
+        id: config
+        shell: bash
+        run: |
+          if [ -f agentic-lib.toml ]; then
+            TEST_CMD=$(grep '^\s*test\s*=' agentic-lib.toml | head -1 | sed 's/.*=\s*"\([^"]*\)".*/\1/')
+          fi
+          echo "test-command=${TEST_CMD:-npm ci && npm test}" >> $GITHUB_OUTPUT
+
+      - name: Run tests before responding
+        id: tests
+        shell: bash
+        run: |
+          set +e
+          ${{ steps.config.outputs.test-command }}
+          EXIT_CODE=$?
+          set -e
+          if [ $EXIT_CODE -eq 0 ]; then
+            echo "result=pass" >> $GITHUB_OUTPUT
+          else
+            echo "result=fail" >> $GITHUB_OUTPUT
+          fi
+
       - name: Get discussion URL
         id: discussion-url
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             let url = '${{ inputs.discussion-url }}' || '';
@@ -134,6 +157,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          TEST_RESULT: ${{ steps.tests.outputs.result }}
         with:
           task: "discussions"
           config: ${{ env.configPath }}

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

@@ -141,15 +141,15 @@ jobs:
       INIT_MISSION_SEED: ${{ needs.params.outputs.mission-seed }}
       INIT_MISSION_TEXT: ${{ needs.params.outputs.mission-text }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: needs.params.outputs.dry-run == 'true'
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: needs.params.outputs.dry-run != 'true'
         with:
           ref: main
           token: ${{ secrets.WORKFLOW_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -204,7 +204,7 @@ jobs:
 
       - name: Update schedule (if requested)
         if: github.repository != 'xn-intenton-z2a/agentic-lib' && needs.params.outputs.schedule != '' && needs.params.outputs.dry-run != 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');

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

@@ -61,16 +61,16 @@ jobs:
   update-schedule:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: inputs.dry-run == 'true' || inputs.dry-run == true
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: inputs.dry-run != 'true' && inputs.dry-run != true
         with:
           ref: main
           token: ${{ secrets.WORKFLOW_TOKEN }}
 
       - name: Update workflow schedule and model
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');

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

@@ -23,17 +23,25 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 24
           cache: "npm"
 
-      - run: npm ci
+      - name: Read test command from config
+        id: config
+        shell: bash
+        run: |
+          if [ -f agentic-lib.toml ]; then
+            TEST_CMD=$(grep '^\s*test\s*=' agentic-lib.toml | head -1 | sed 's/.*=\s*"\([^"]*\)".*/\1/')
+          fi
+          echo "test-command=${TEST_CMD:-npm ci && npm test}" >> $GITHUB_OUTPUT
 
       - name: Install sub-project dependencies (agentic-lib dev only)
         if: hashFiles('src/actions/agentic-step/package.json') != ''
         run: cd src/actions/agentic-step && npm ci
 
-      - run: npm test
+      - name: Run tests
+        run: ${{ steps.config.outputs.test-command }}

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

@@ -154,7 +154,7 @@ jobs:
     steps:
       - name: PR cleanup
         if: github.repository != 'xn-intenton-z2a/agentic-lib' && needs.params.outputs.dry-run != 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const owner = context.repo.owner;
@@ -224,10 +224,10 @@ jobs:
       needs.params.outputs.mode == 'full' || needs.params.outputs.mode == 'dev-only' || needs.params.outputs.mode == 'review-only'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Gather telemetry
         id: gather
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
@@ -302,9 +302,9 @@ jobs:
       needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -337,11 +337,22 @@ jobs:
       needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - name: Check mission-complete signal
+        id: mission-check
+        run: |
+          if [ -f MISSION_COMPLETE.md ]; then
+            echo "mission-complete=true" >> $GITHUB_OUTPUT
+            echo "Mission is complete — skipping budget-consuming tasks"
+            cat MISSION_COMPLETE.md
+          else
+            echo "mission-complete=false" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -364,6 +375,7 @@ jobs:
           echo "libraryWritablePaths=${LIBRARY};${SOURCES}" >> $GITHUB_OUTPUT
 
       - name: Maintain features
+        if: steps.mission-check.outputs.mission-complete != 'true'
         uses: ./.github/agentic-lib/actions/agentic-step
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -376,6 +388,7 @@ jobs:
           model: ${{ needs.params.outputs.model }}
 
       - name: Maintain library
+        if: steps.mission-check.outputs.mission-complete != 'true'
         uses: ./.github/agentic-lib/actions/agentic-step
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -403,11 +416,11 @@ jobs:
       needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -422,8 +435,19 @@ jobs:
         working-directory: .github/agentic-lib/actions/agentic-step
         run: npm ci
 
+      - name: Check mission-complete signal
+        id: fix-mission-check
+        run: |
+          if [ -f MISSION_COMPLETE.md ]; then
+            echo "mission-complete=true" >> $GITHUB_OUTPUT
+            echo "Mission is complete — skipping fix-stuck"
+          else
+            echo "mission-complete=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Find and fix stuck PRs
-        uses: actions/github-script@v7
+        if: steps.fix-mission-check.outputs.mission-complete != 'true'
+        uses: actions/github-script@v8
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
@@ -483,14 +507,14 @@ jobs:
             }
 
       - name: Checkout PR branch
-        if: env.FIX_PR_NUMBER != ''
+        if: env.FIX_PR_NUMBER != '' && steps.fix-mission-check.outputs.mission-complete != 'true'
         run: |
           gh pr checkout ${{ env.FIX_PR_NUMBER }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: "Tier 1: Auto-resolve trivial merge conflicts"
-        if: env.FIX_PR_NUMBER != '' && env.FIX_REASON == 'merge conflicts'
+        if: env.FIX_PR_NUMBER != '' && env.FIX_REASON == 'merge conflicts' && steps.fix-mission-check.outputs.mission-complete != 'true'
         id: trivial-resolve
         run: |
           git fetch origin main
@@ -522,6 +546,7 @@ jobs:
       - name: "Tier 2: LLM fix (conflicts or failing checks)"
         if: |
           env.FIX_PR_NUMBER != '' &&
+          steps.fix-mission-check.outputs.mission-complete != 'true' &&
           (env.FIX_REASON != 'merge conflicts' ||
            steps.trivial-resolve.outputs.resolved == 'none')
         uses: ./.github/agentic-lib/actions/agentic-step
@@ -534,11 +559,11 @@ jobs:
           config: ${{ needs.params.outputs.config-path }}
           instructions: ".github/agentic-lib/agents/agent-apply-fix.md"
           pr-number: ${{ env.FIX_PR_NUMBER }}
-          test-command: "npm test"
+          # test-command read from [execution].test in agentic-lib.toml
           model: ${{ needs.params.outputs.model }}
 
       - name: Commit and push fixes
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.FIX_PR_NUMBER != ''
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.FIX_PR_NUMBER != '' && steps.fix-mission-check.outputs.mission-complete != 'true'
         uses: ./.github/agentic-lib/actions/commit-if-changed
         with:
           commit-message: "agentic-step: fix failing tests / resolve conflicts"
@@ -552,9 +577,9 @@ jobs:
       needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -597,12 +622,12 @@ jobs:
       needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "24"
 
@@ -631,9 +656,21 @@ jobs:
           DEPS=$(yq -r '.paths.dependenciesFilepath.path // "package.json"' "$CONFIG")
           echo "writablePaths=${SOURCE};${TESTS};${FEATURES};${DOCS};${LIBRARY};${SOURCES};${README};${DEPS}" >> $GITHUB_OUTPUT
 
+      - name: Check mission-complete signal
+        id: dev-mission-check
+        run: |
+          if [ -f MISSION_COMPLETE.md ]; then
+            echo "mission-complete=true" >> $GITHUB_OUTPUT
+            echo "Mission is complete — skipping dev transformation"
+            cat MISSION_COMPLETE.md
+          else
+            echo "mission-complete=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Find target issue
+        if: steps.dev-mission-check.outputs.mission-complete != 'true'
         id: issue
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const specificIssue = '${{ needs.params.outputs.issue-number }}';
@@ -673,7 +710,7 @@ jobs:
           task: "transform"
           config: ${{ needs.params.outputs.config-path }}
           instructions: ".github/agentic-lib/agents/agent-issue-resolution.md"
-          test-command: "npm test"
+          # test-command read from [execution].test in agentic-lib.toml
           model: ${{ needs.params.outputs.model }}
           issue-number: ${{ steps.issue.outputs.issue-number }}
           writable-paths: ${{ steps.config.outputs.writablePaths }}
@@ -687,7 +724,7 @@ jobs:
 
       - name: Create PR and attempt merge
         if: github.repository != 'xn-intenton-z2a/agentic-lib' && steps.issue.outputs.issue-number != '' && needs.params.outputs.dry-run != 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const owner = context.repo.owner;
@@ -779,7 +816,7 @@ jobs:
     if: always() && needs.params.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

package/README.md

@@ -172,22 +172,37 @@ contributing = "CONTRIBUTING.md"
 library-sources = "SOURCES.md"
 
 [execution]
-build = "npm run build"
-test = "npm test"
-start = "npm run start"
+test = "npm ci && npm test"
 
 [limits]
-feature-issues = 2
-maintenance-issues = 1
-attempts-per-branch = 3
-attempts-per-issue = 2
+max-feature-issues = 2
+max-maintenance-issues = 1
+max-attempts-per-branch = 3
+max-attempts-per-issue = 2
 features-limit = 4
 library-limit = 32
 
+[tuning]
+profile = "recommended"       # min | recommended | max
+# model = "gpt-5-mini"        # override model per-profile
+# transformation-budget = 8   # max code-changing cycles per run
+
 [bot]
 log-file = "intentïon.md"
 ```
 
+### Tuning Profiles
+
+The `profile` setting controls all tuning defaults. Three profiles are built in:
+
+| Profile | Budget | Source scan | Issues | Best for |
+|---------|--------|-------------|--------|----------|
+| `min` | 4 cycles | 3 files, 1000 chars | 5, 14d stale | CI testing, quick validation |
+| `recommended` | 8 cycles | 10 files, 5000 chars | 20, 30d stale | Balanced cost/quality |
+| `max` | 32 cycles | 50 files, 20000 chars | 100, 90d stale | Complex missions |
+
+Override individual knobs in `[tuning]` to deviate from a profile. Limits (`[limits]`) also scale with the profile.
+
 The YAML config at `.github/agentic-lib/agents/agentic-lib.yml` is also supported as a fallback.
 
 ## The `agentic-step` Action
@@ -217,6 +232,7 @@ npx @xn-intenton-z2a/agentic-lib transform            # advance code toward the
 npx @xn-intenton-z2a/agentic-lib maintain-features     # generate feature files from mission
 npx @xn-intenton-z2a/agentic-lib maintain-library      # update library docs from SOURCES.md
 npx @xn-intenton-z2a/agentic-lib fix-code              # fix failing tests
+npx @xn-intenton-z2a/agentic-lib iterate               # run N cycles with budget tracking
 ```
 
 All task commands accept these flags:
@@ -226,6 +242,9 @@ 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 |
+| `--cycles <N>` | from budget | Max iteration cycles (iterate only) |
+| `--steps <list>` | all three | Comma-separated steps per cycle (iterate only) |
+| `--mission <name>` | hamming-distance | Init with --purge before iterating (iterate only) |
 
 ### Example: Full Walkthrough
 
@@ -278,6 +297,28 @@ Use `--dry-run` to see what prompt would be sent without calling the SDK:
 npx @xn-intenton-z2a/agentic-lib transform --dry-run
 ```
 
+### Iterator
+
+The `iterate` command runs multiple cycles of maintain → transform → fix with automatic stop conditions and budget tracking:
+
+```bash
+# Init a mission and iterate with default budget
+npx @xn-intenton-z2a/agentic-lib iterate --mission fizz-buzz --model gpt-5-mini
+
+# Run 4 cycles on an existing workspace
+npx @xn-intenton-z2a/agentic-lib iterate --cycles 4
+
+# Transform-only cycles (skip maintain)
+npx @xn-intenton-z2a/agentic-lib iterate --steps transform,fix-code --cycles 3
+```
+
+**Stop conditions:**
+- Tests pass for 2 consecutive cycles
+- No files change for 2 consecutive cycles
+- Transformation budget exhausted (configurable via `transformation-budget` in `agentic-lib.toml`)
+
+Each cycle logs `**agentic-lib transformation cost:** 1` to `intentïon.md` when source files change. The iterator reads these to track cumulative cost against the budget.
+
 ### Environment
 
 | Variable | Required | Purpose |
@@ -301,6 +342,8 @@ Built-in safety mechanisms:
 
 - **WIP limits** -- maximum concurrent issues to prevent runaway generation
 - **Attempt limits** -- maximum retries per branch and per issue
+- **Transformation budget** -- caps code-changing cycles per run (profile-scaled)
+- **Mission-complete signal** -- `MISSION_COMPLETE.md` gates budget-consuming jobs without LLM calls
 - **Path enforcement** -- writable and read-only path separation
 - **TDD mode** -- optionally require tests before implementation
 - **Mission protection** -- MISSION.md is read-only to the agent
@@ -331,7 +374,7 @@ src/
 
 ### Testing
 
-269 unit tests across 22 test files, plus system tests:
+393 unit tests across 26 test files, plus system tests:
 
 ```bash
 npm test                  # Run all tests (vitest)

package/agentic-lib.toml

@@ -22,21 +22,20 @@ contributing = "test/CONTRIBUTING.md"           #@dist "CONTRIBUTING.md"
 library-sources = "test/SOURCES.md"             #@dist "SOURCES.md"
 
 [execution]
-build = "npm run build"
-test = "npm test"
-start = "npm run start"
+test = "npm ci && npm test"
 
 [limits]
-feature-issues = 2
-maintenance-issues = 1
-attempts-per-branch = 3
-attempts-per-issue = 2
-features-limit = 2
-library-limit = 32
+# Override profile defaults here. Omit to use the active profile's values.
+# max-feature-issues = 2
+# max-maintenance-issues = 1
+# max-attempts-per-branch = 3
+# max-attempts-per-issue = 2
+# features-limit = 2
+# library-limit = 32
 
 [tuning]
-# Profile sets defaults for all tuning knobs: min | recommended | max
-# min = fast & cheap (CI testing), recommended = balanced, max = thorough
+# Profile sets defaults for all tuning and limit knobs: min | recommended | max
+# Profile definitions live in [profiles.*] sections below.
 profile = "min"                                  #@dist "recommended"
 #
 # Model selection — each has different strengths:
@@ -50,12 +49,84 @@ model = "gpt-5-mini"
 # Override individual knobs below. Omit or comment out to use profile defaults.
 # reasoning-effort = "low"       # low | medium | high | none (none = disable entirely)
 infinite-sessions = false        # set to true for long sessions with compaction
-# features-scan = 3              # feature files to include in prompts
-# source-scan = 3                # source files to include
-# source-content = 1000          # max chars per source file
-# issues-scan = 5                # open issues to include
-# document-summary = 500         # max chars for document summaries
-# discussion-comments = 5        # discussion comments to include
+# transformation-budget = 4      # max code-changing cycles per run (0 = unlimited)
+# max-feature-files = 3
+# max-source-files = 3
+# max-source-chars = 1000
+# max-test-chars = 500
+# max-issues = 5
+# issue-body-limit = 200
+# stale-days = 14
+# max-summary-chars = 500
+# max-discussion-comments = 5
+
+# ─── Profile Definitions ────────────────────────────────────────────
+# Each profile defines tuning and limits defaults. The active profile
+# is set by [tuning].profile above. Override individual values in
+# [tuning] or [limits] to deviate from the active profile.
+
+[profiles.min]
+# Fast & cheap — CI testing, quick validation, budget-conscious iteration.
+reasoning-effort = "low"                # low | medium | high | none
+infinite-sessions = false               # enable session compaction for long runs
+transformation-budget = 4              # max code-changing cycles per run
+max-feature-files = 3                      # max feature files included in prompts
+max-source-files = 3                        # max source files included in prompts
+max-source-chars = 1000                  # max chars of each source file's content included in prompts
+max-test-chars = 500                     # max chars of each test file's content included in prompts
+max-issues = 5                        # max open issues included in prompts
+issue-body-limit = 200                 # max chars of each issue's body text included in prompts
+stale-days = 14                        # days since last activity before an issue is considered stale and excluded
+max-summary-chars = 500                 # max chars of each document's summary included in prompts
+max-discussion-comments = 5               # max recent discussion comments (newest first) included in prompts
+max-feature-issues = 1                     # max concurrent feature development issues
+max-maintenance-issues = 1                 # max concurrent maintenance issues
+max-attempts-per-branch = 2               # max transform attempts before abandoning a branch
+max-attempts-per-issue = 1                 # max transform attempts before abandoning an issue
+features-limit = 2                     # max feature files in features/ directory
+library-limit = 8                      # max library entries in library/ directory
+
+[profiles.recommended]
+# Balanced — good results without excessive cost. Default for consumer repos.
+reasoning-effort = "medium"            # low | medium | high | none
+infinite-sessions = true               # enable session compaction for long runs
+transformation-budget = 8             # max code-changing cycles per run
+max-feature-files = 10                     # max feature files included in prompts
+max-source-files = 10                       # max source files included in prompts
+max-source-chars = 5000                  # max chars of each source file's content included in prompts
+max-test-chars = 3000                    # max chars of each test file's content included in prompts
+max-issues = 20                       # max open issues included in prompts
+issue-body-limit = 500                 # max chars of each issue's body text included in prompts
+stale-days = 30                        # days since last activity before an issue is considered stale and excluded
+max-summary-chars = 2000                # max chars of each document's summary included in prompts
+max-discussion-comments = 10              # max recent discussion comments (newest first) included in prompts
+max-feature-issues = 2                     # max concurrent feature development issues
+max-maintenance-issues = 1                 # max concurrent maintenance issues
+max-attempts-per-branch = 3               # max transform attempts before abandoning a branch
+max-attempts-per-issue = 2                 # max transform attempts before abandoning an issue
+features-limit = 4                     # max feature files in features/ directory
+library-limit = 32                     # max library entries in library/ directory
+
+[profiles.max]
+# Thorough — maximum context, highest quality. For complex missions.
+reasoning-effort = "high"              # low | medium | high | none
+infinite-sessions = true               # enable session compaction for long runs
+transformation-budget = 32            # max code-changing cycles per run
+max-feature-files = 50                     # max feature files included in prompts
+max-source-files = 50                       # max source files included in prompts
+max-source-chars = 20000                 # max chars of each source file's content included in prompts
+max-test-chars = 15000                   # max chars of each test file's content included in prompts
+max-issues = 100                      # max open issues included in prompts
+issue-body-limit = 2000                # max chars of each issue's body text included in prompts
+stale-days = 90                        # days since last activity before an issue is considered stale and excluded
+max-summary-chars = 10000               # max chars of each document's summary included in prompts
+max-discussion-comments = 25              # max recent discussion comments (newest first) included in prompts
+max-feature-issues = 4                     # max concurrent feature development issues
+max-maintenance-issues = 2                 # max concurrent maintenance issues
+max-attempts-per-branch = 5               # max transform attempts before abandoning a branch
+max-attempts-per-issue = 4                 # max transform attempts before abandoning an issue
+features-limit = 8                     # max feature files in features/ directory
+library-limit = 64                     # max library entries in library/ directory
 
 [bot]
 log-file = "test/intentïon.md"                  #@dist "intentïon.md"