@jenga-ai/agent 1.0.0

package/skills/publish/wizards/npm.md

@@ -0,0 +1,224 @@
+# npm setup wizard
+
+Use this template to collect the values required for an `npm` publish target.
+Each section maps directly to a field in `publish.json`.
+
+Before running the prompts, load the project's `package.json` (if present) so
+`name` can be offered as the default for `package_name`. If `publish.json`
+already contains a target whose `type` is `npm`, ask the user whether to
+**overwrite** the existing target or **update** individual fields — do not
+silently replace it.
+
+After collecting answers, write the target block to `publish.json` (create the
+file from the base scaffold if it does not exist) and generate
+`project/instructions/E26_S04_T02_INSTRUCTIONS.md` documenting the `NPM_TOKEN`
+prerequisite. See the "Post-collection actions" section at the bottom for the
+full write sequence.
+
+## Question: package_name
+
+Maps to: `targets[].npm.package_name`
+
+Enter the npm package name as it should appear in the registry.
+If a `package.json` exists at the project root, offer its `name` field as the
+default. Supports scoped names such as `@scope/name`.
+
+## Expected format:
+
+Lowercase, url-safe name matching `^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$`
+(e.g. `jenga-agent`, `@my-org/utils`). Max 214 characters.
+
+## Question: access
+
+Maps to: `targets[].npm.access`
+
+Choose the registry access level for this package.
+`public` publishes an openly-installable package. `restricted` publishes a
+private package (requires a paid npm plan or a private registry such as
+GitHub Packages).
+
+## Expected format:
+
+One of: `public`, `restricted`. Press Enter to accept the default (`public`).
+
+## Question: dist_tag
+
+Maps to: `targets[].npm.dist_tag`
+
+Enter the npm dist-tag applied to this publish. `latest` is the default
+install tag; use tags like `next` or `beta` for pre-releases so that
+`npm install <pkg>` continues to resolve to the current stable version.
+
+## Expected format:
+
+Lowercase tag matching `^[a-z0-9][a-z0-9._-]*$` (e.g. `latest`, `next`,
+`beta`). Press Enter to accept the default (`latest`).
+
+## Question: registry
+
+Maps to: `targets[].npm.registry`
+
+Enter the registry URL to publish to.
+For the public npm registry, accept the default. For GitHub Packages, use
+`https://npm.pkg.github.com`. For a private/internal registry, use the URL
+provided by your registry operator.
+
+## Expected format:
+
+An absolute `https://` URL (e.g. `https://registry.npmjs.org`,
+`https://npm.pkg.github.com`). Press Enter to accept the default
+(`https://registry.npmjs.org`).
+
+## Question: dry_run
+
+Maps to: `targets[].notes` (captured as a wizard-authored note; there is no
+dedicated schema field for dry-run because it is a per-invocation pipeline
+concern, not persistent target config).
+
+Ask whether the first deploy against this target should be executed as a
+dry-run (`npm publish --dry-run`). A dry-run packs and validates the tarball
+and contacts the registry without publishing, letting you confirm the target
+config end-to-end before spending a real version bump.
+
+If the user answers **yes**, append a line to the target's `notes` field
+along the lines of:
+
+> First deploy should be a dry-run (`npm publish --dry-run`) per wizard
+> preference. Remove this note after the dry-run passes.
+
+If the user answers **no**, do not add a dry-run note; the pipeline will
+publish for real on the first run.
+
+## Expected format:
+
+Yes/no. Press Enter to accept the default (`yes` — recommended for the first
+deploy).
+
+## Prerequisite: NPM_TOKEN
+
+The npm pipeline reads the auth token from the `NPM_TOKEN` environment
+variable at publish time (`skills/publish/adapters/npm.md` defines this
+contract). The wizard does not collect the token value — that would be
+unsafe. Instead, at the end of the wizard, write the following instructions
+file so the user knows exactly what to configure:
+
+**File to write:** `project/instructions/E26_S04_T02_INSTRUCTIONS.md`
+
+**Contents (verbatim template):**
+
+```markdown
+# npm Publish — Setup Instructions
+
+**Epic**: E26 — NPM-Compatible Distribution
+**Required before**: running `/publish deploy` against the npm target
+
+## Overview
+
+The npm publish pipeline authenticates with the target registry using an
+automation token stored in the `NPM_TOKEN` environment variable. This file
+walks you through obtaining that token and making it available to the
+pipeline.
+
+## Steps
+
+1. Sign in to https://www.npmjs.com with the account that owns (or is a
+   maintainer of) the package.
+2. Open **Account Settings** → **Access Tokens** → **Generate New Token**.
+3. Choose **Automation** (this token type bypasses 2FA prompts, which is
+   required for CI/scripted publishes).
+4. Copy the generated token immediately — npm shows it only once.
+5. Store the token in the environment the pipeline runs in:
+   - **Local development**: add `export NPM_TOKEN=<token>` to a shell rc
+     file that is loaded before running `/publish deploy`, or place it in
+     a git-ignored `.env` file and source it in your shell.
+   - **CI (GitHub Actions, etc.)**: add `NPM_TOKEN` as an encrypted
+     repository secret and expose it to the publish job via
+     `env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }}`.
+   - **GitHub Packages**: use a GitHub Personal Access Token with
+     `write:packages` scope in place of an npm.js token, and export it as
+     `NPM_TOKEN` (or `NODE_AUTH_TOKEN` if your `.npmrc` uses that name).
+6. Never commit the token value to the repository. `.env` files, shell rc
+   files, and CI logs must all be treated as sensitive.
+
+## Verification
+
+Run `npm whoami --registry <your-registry-url>` with `NPM_TOKEN` set. It
+should print your npm username. If it prints an anonymous / not-logged-in
+error, the token is missing, expired, or scoped to the wrong registry.
+
+## Notes
+
+- Automation tokens do not expire by default but can be revoked at any time
+  from the npm Access Tokens page.
+- If you rotate the token, update the value everywhere it is stored (local
+  env, CI secrets) — the pipeline reads it fresh on every invocation.
+- The `secrets.NPM_TOKEN` entry in `publish.json` is a reference like
+  `"$NPM_TOKEN"`, not the token value itself. The publish adapter resolves
+  the reference against the current environment.
+```
+
+Do not skip generating this file, even if the user says the token is already
+configured — the instructions file is the durable record of what the
+pipeline expects.
+
+## Post-collection actions
+
+Once all five answers have been collected, perform the following steps in
+order:
+
+1. **Load or scaffold `publish.json`.** If the file does not exist at the
+   project root, create it from the base scaffold with `version: 1`,
+   populated `defaults`, and an empty `targets` array. If it does exist,
+   parse and preserve every unrelated field.
+2. **Check for an existing npm target.** Scan `targets[]` for any entry with
+   `"type": "npm"`. If one exists, ask the user:
+   - **overwrite** — replace the entire target block with the wizard output
+   - **update** — merge the wizard answers into the existing target
+     field-by-field, keeping any user-added fields (e.g. custom `checks`
+     or `notes`) intact.
+   If none exists, append a new target block.
+3. **Write the target block.** Emit it in the exact shape below (with
+   dry-run note only if the user answered yes):
+
+   ```json
+   {
+     "name": "npm-<package-slug>",
+     "type": "npm",
+     "platform": "npm-registry",
+     "checks": {
+       "pre": ["lint", "type-check"],
+       "post": ["smoke-test"]
+     },
+     "secrets": {
+       "NPM_TOKEN": "$NPM_TOKEN"
+     },
+     "npm": {
+       "package_name": "<answer>",
+       "access": "<answer>",
+       "registry": "<answer>",
+       "dist_tag": "<answer>"
+     },
+     "notes": "<optional dry-run note per user preference>"
+   }
+   ```
+
+   Notes on shape:
+   - `name` is derived from the package name (slugified, lowercased). If a
+     collision exists, suffix with `-2`, `-3`, etc.
+   - `platform` is `npm-registry` for `https://registry.npmjs.org`. If the
+     user supplied `https://npm.pkg.github.com`, set `platform` to
+     `github-packages` instead.
+   - `secrets` includes `NPM_TOKEN` by default. If the user's registry uses
+     `NODE_AUTH_TOKEN` (common with GitHub Packages `.npmrc` setups), swap
+     the key accordingly — the schema accepts either.
+   - Omit the `notes` field entirely when the user declined the dry-run.
+4. **Validate against the schema.** Run `scripts/validate_publish_config.sh`
+   (or the equivalent AJV invocation) before saving. If validation fails,
+   report the error and abort — do not write a broken `publish.json`.
+5. **Write the instructions file.** Create
+   `project/instructions/E26_S04_T02_INSTRUCTIONS.md` with the verbatim
+   template from the "Prerequisite: NPM_TOKEN" section above. Create the
+   `project/instructions/` directory if it does not exist.
+6. **Report to the user.** Print a short summary listing (a) the target
+   block written, (b) the path to the instructions file, and (c) the exact
+   env var they must set before running `/publish deploy`.

package/skills/reconcile/SKILL.md

@@ -0,0 +1,93 @@
+---
+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".
+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.
+
+## Instructions
+
+### 0. Read configuration
+Read `project/configs/workflow.json` for board paths. Fall back to `project/board/` if missing.
+The statuses that count as "completed" are: **Done**, **Passed**, **Passed with remarks**.
+
+### 1. Snapshot the board
+Scan every file in `epics/`, `stories/`, and `tasks/`. For each item record:
+- `id`, `title`, `status` (the **pre-reconcile** status — needed in phase 4)
+- `date_completed` (if set)
+
+Also read `project/todo.md` and parse every non-comment, non-blank line into a list of todo entries.
+
+### 2. Verify "completed" tasks — are they really implemented?
+For every task whose status is a completed status:
+
+1. **Search git history** — run `git log --all --oneline --grep="<task_id>"` (e.g. `E01_S01_T01`). A matching commit is strong evidence of implementation.
+2. **Check documentation artefacts** — look for a plan or summary file under `project/documentation/plans/` or `project/documentation/summaries/` whose name contains the task ID.
+3. **Read the task's acceptance criteria** and spot-check the codebase for the key deliverables described (e.g. if the task says "create `scripts/foo.sh`", verify the file exists).
+
+If implementation **is confirmed** — no action needed; the status is correct.
+
+If implementation **cannot be confirmed**:
+1. List git worktrees (`git worktree list`) and branches (`git branch --all`) that appear to match the task ID or its slug (the branch naming convention is `<E##_S##_T##-short-slug>`).
+2. If a matching worktree or branch exists:
+   - Inform the user and ask for confirmation before merging.
+   - On confirmation, merge the branch into the current branch (`git merge <branch>`).
+   - After a successful merge, the task stays at its completed status.
+   - If the merge has conflicts, alert the user and **do not** change the status — leave it for manual resolution.
+3. If **no** matching branch or worktree exists:
+   - Change the task's status to **Pending** in its board file.
+   - Clear `date_started` and `date_completed`.
+   - Report the demotion.
+
+### 3. Verify "incomplete" tasks — are they secretly implemented?
+For every task whose status is **not** a completed status (Pending, In Progress, Running, Blocked, etc.):
+
+1. **Search git history** for commits referencing the task ID.
+2. **Check documentation artefacts** as in phase 2.
+3. **Spot-check acceptance criteria** against the codebase.
+
+If implementation **is confirmed**:
+- Update the task's status to **Passed** in its board file.
+- Set `date_completed` to today (ISO 8601).
+- If the task is listed in `project/todo.md`, **comment it out** by wrapping the line:
+  ```
+  <!-- RECONCILED: <original line> -->
+  ```
+- Report the promotion.
+
+If implementation **is not confirmed** — no action needed; the status is already correct.
+
+### 4. Roll up story and epic statuses
+After all tasks have been reconciled:
+
+- For each **story**: if all of its tasks are now in a completed status, set the story to **Done** (if not already). If any task was demoted, and the story was previously completed, set the story back to **In Progress**.
+- For each **epic**: apply the same roll-up logic over its stories.
+
+#### DoD Gap Detection
+
+After rolling up statuses, scan every story whose status is a completed status (`Passed`, `Passed with remarks`, `Done`) for unchecked Definition of Done items:
+
+1. Read the story file and locate the `## Definition of Done` section. If the section is absent, skip this story gracefully (no error).
+2. Scan the DoD section for any lines matching `^- \[ \]` (unchecked checkboxes).
+3. If unchecked boxes are found: record the story ID, story title, and the full text of each unchecked item.
+4. If all DoD boxes are already ticked (`- [x]`), or the DoD section is absent, no gap is reported for that story.
+
+At the end of Phase 4, if any DoD gaps were found across any stories, include a **"DoD Gaps"** section in the reconcile report (see `assets/report_format.md`) listing each affected story and its unchecked items.
+
+**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`
+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`.
+
+If no changes were made, print: `Board and todo.md are in sync — nothing to reconcile. ✅`

package/skills/reconcile/assets/report_format.md

@@ -0,0 +1,44 @@
+## Reconciliation Report Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RECONCILIATION REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Scanned: <N> epics, <N> stories, <N> tasks
+
+⬇️  DEMOTED (were Done/Passed → now Pending)
+   🔧 E##_S##_T## · <Task Title>  — no commits or artefacts found
+
+🔀 MERGED (worktree branch merged)
+   🔧 E##_S##_T## · <Task Title>  — merged branch <branch-name>
+
+⬆️  PROMOTED (were incomplete → now Passed)
+   🔧 E##_S##_T## · <Task Title>  — commits found, acceptance criteria met
+
+🔄 ROLL-UP CHANGES
+   📖 E##_S## · <Story Title>  — <old status> → <new status>
+   📦 E## · <Epic Title>  — <old status> → <new status>
+
+⚠️  DOD GAPS (completed stories with unchecked Definition of Done items)
+   📖 E##_S## · <Story Title>
+      - [ ] <unchecked DoD item text>
+      - [ ] <unchecked DoD item text>
+   📖 E##_S## · <Story Title>
+      - [ ] <unchecked DoD item text>
+
+🧹 TODO CLEANUP
+   Removed: <N> stale entries
+   Commented out: <N> newly-reconciled entries
+   todo.md deleted: yes/no
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Section rules
+
+- Omit any section that has zero items (e.g. if nothing was demoted, skip the DEMOTED block entirely).
+- The MERGED section should include the branch name that was merged.
+- The TODO CLEANUP section is always shown if `project/todo.md` existed at the start, even if zero changes were made (in that case show all counts as 0).
+- If `project/todo.md` did not exist, omit the TODO CLEANUP section.
+- The DOD GAPS section is omitted if no completed stories have unchecked DoD checkboxes.

package/skills/reconcile-origin/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: reconcile-origin
+description: Sync the current (or specified) branch with origin by rebasing local commits on top of the latest upstream state.
+keywords:
+  - "sync branch"
+  - "rebase origin"
+  - "reconcile origin"
+  - "pull rebase"
+examples:
+  - "sync my branch with origin"
+  - "rebase local commits on top of origin"
+  - "reconcile-origin feature/my-branch"
+---
+
+# Reconcile Origin
+
+Use this skill to rebase local work on top of the latest `origin/<branch>` state without re-implementing git logic inline.
+
+## Instructions
+
+1. Determine the target branch:
+   - If the user passed an argument, use that branch name.
+   - Otherwise, use the current branch name.
+
+2. Invoke `.agents/skills/reconcile-origin/scripts/reconcile-origin.sh [<branch>]` and capture stdout.
+   - Do not run any inline git commands in this skill — all git work is handled by the script.
+   - The script handles dirty-worktree detection internally and returns `{"status":"error","code":"uncommitted_changes",...}` if the working tree is not clean.
+
+3. Parse the script's JSON response and react by `status`:
+   - `ok`
+     - Report success.
+     - Include the branch name and `rebased_commits` count.
+   - `local_branch_missing`
+     - If `remote_exists` is `true`, present options in this format:
+
+       What would you like to do?
+       1. Create a local tracking branch for `<branch>` and continue `/reconcile-origin`
+       2. Cancel and inspect the branch setup manually
+       3. Other (describe below)
+
+     - If the user chooses option 1, invoke `.agents/skills/reconcile-origin/scripts/reconcile-origin.sh <branch> --create-tracking`.
+     - If `remote_exists` is `false`, explain that neither a local branch nor `origin/<branch>` was found and stop.
+   - `conflict`
+     - Present one structured conflict rapport per item in `conflicts`.
+     - For each conflict include:
+       - File path
+       - The `description`
+       - `local_section`
+       - `origin_section`
+     - Then present options in this format:
+
+       What would you like to do?
+       1. Resolve the conflict now by merging both sides carefully
+       2. Keep the local intent, then re-apply the essential upstream change manually
+       3. Handle it later — leave annotated conflict markers in the file and continue the scripted flow
+       4. Other (describe below)
+
+     - If the user chooses “Handle it later”, invoke `.agents/skills/reconcile-origin/scripts/reconcile-origin.sh <branch> --handle-later <file>` for the selected conflict file.
+   - `handled_later`
+     - Confirm that the selected file was annotated for later resolution.
+     - Tell the user the conflict markers were intentionally preserved with a `# RECONCILE-ORIGIN CONFLICT:` note.
+   - `error`
+     - Report the script's `message` clearly.
+     - If `code` indicates `branch_not_found_on_origin`, explain that the remote branch could not be fetched.
+     - If `code` indicates `uncommitted_changes`, remind the user to stash or commit first.
+
+4. When presenting a conflict rapport, make the incompatibility explicit.
+   - Explain what the local section is trying to preserve.
+   - Explain what the origin section changed upstream.
+   - Recommend at least two concrete resolution paths before offering “Handle it later” as the final actionable option.
+
+## Guard Rails
+
+- All git work must go through `.agents/skills/reconcile-origin/scripts/reconcile-origin.sh`.
+- Do not inline fetch, checkout, pull, merge, rebase, or status commands in this skill body.