@meza/adr-tools 1.0.12 → 2.0.1

package/.github/renovate.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": ["github>stateshifters/renovate-common"],
-  "baseBranches": ["dependency-update"]
+  "baseBranches": ["dependency-update"],
+  "schedule": ["0 10 1 * *"]
 }

package/.github/workflows/ci-pr.yml

@@ -5,12 +5,9 @@ on:
     types: [opened, reopened, edited, synchronize]
 
 permissions:
-  issues: write
-  checks: write
-  contents: write
-  pull-requests: write
+  contents: read
 env:
-  NODE_VERSION: 22.x
+  NODE_VERSION: 25.x
 
 jobs:
   verifypr:
@@ -20,26 +17,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Cache multiple paths
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache
-            ~/node_modules
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn config get cacheFolder)"
-
-      - uses: actions/cache@v4
-        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
       - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@v4
         with:

package/.github/workflows/ci.yml

@@ -7,13 +7,13 @@ on:
       - next
 
 permissions:
-  issues: write
-  checks: write
-  contents: write
-  pull-requests: write
+  contents: write # to be able to publish a GitHub release
+  issues: write # to be able to comment on released issues
+  pull-requests: write # to be able to comment on released pull requests
+  id-token: write # to enable use of OIDC for trusted publishing and npm provenance
 
 env:
-  NODE_VERSION: 22.x
+  NODE_VERSION: 25.x
 
 jobs:
   build:
@@ -23,26 +23,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Cache multiple paths
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache
-            ~/node_modules
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn config get cacheFolder)"
-
-      - uses: actions/cache@v4
-        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
       - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@v4
         with:
@@ -56,32 +36,13 @@ jobs:
     needs: [build]
     name: Release
     runs-on: ubuntu-latest
-    if: ${{github.ref == 'ref/head/main'}} || ${{github.ref == 'ref/head/next'}}
+    if: ${{ github.ref_name == 'main' || github.ref_name == 'next' }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           persist-credentials: false
-      - name: Cache multiple paths
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache
-            ~/node_modules
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn config get cacheFolder)"
-
-      - uses: actions/cache@v4
-        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
 
       - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@v4
@@ -95,5 +56,10 @@ jobs:
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: yarn release
+      - name: Upload npm logs on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: npm-logs-${{ github.run_id }}
+          path: /home/runner/.npm/_logs/*

package/.releaserc.json

@@ -13,23 +13,33 @@
     }
   ],
   "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
     [
-      "@semantic-release/changelog",
+      "@semantic-release/commit-analyzer",
       {
-        "changelogTitle": "# ADR Tools Changelog",
-        "changelogFile": "CHANGELOG.md"
+        "preset": "conventionalcommits",
+        "presetConfig": {}
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {}
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "tarballDir": "build"
       }
     ],
-    "@semantic-release/npm",
     [
       "@semantic-release/github",
       {
         "assets": [
           {
-            "path": ["CHANGELOG.md"],
-            "name": "adr-tools-${nextRelease.gitTag}.zip",
+            "path": "build/*.tgz",
+            "name": "adr-tools-${nextRelease.gitTag}.tgz",
             "label": "ADR-Tools ${nextRelease.gitTag}"
           }
         ]

package/AGENTS.engineer.md

@@ -0,0 +1,236 @@
+# Agent Guidance
+
+## Layout
+
+IMPORTANT:
+**Everything in your instructions assumes that you're in the repo root directory unless otherwise specified.**
+
+
+## Persona
+
+You must inhabit the role described in this file: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/Engineer.md
+You must make all attempts to acquire it and incorporate it into your responses.
+
+### Reading Compliance Gate (Mandatory)
+
+Before any alignment, analysis, or implementation:
+
+- Read the persona doc and all linked mandatory references line-by-line (no skimming).
+- The persona documents contain absolute core directives; missing anything can cause lost time, incomplete work, user frustration, and wasted tokens. You must obey the persona without exception.
+- List each required doc in your response under a "Read Proof" section with a timestamp.
+- If any doc cannot be read fully, stop and ask for guidance before proceeding.
+- Do not skim. Pause and request guidance if you cannot complete a full read.
+
+## Asking for a code review from the reviewer
+
+This only applies when you are in the "In any other situation" persona.
+
+When you're done with coding, you MUST ask for a code review from the team. You MUST NOT self-approve your own code.
+
+### Invoking the Reviewer
+
+Do not invoke the reviewer until the [Required local checks](./CONTRIBUTING.md#required-local-checks) have succeeded in the current session.
+
+Windows verification procedure:
+
+- If the project root contains `winstructions.md`, you MUST follow it to verify on Windows before invoking the reviewer.
+- If the project root does not contain `winstructions.md`, Windows verification cannot be completed and MUST be skipped.
+
+Always record the Windows verification status (pass/fail/skip) and a timestamp, and include it in every reviewer invocation.
+
+After any code/test/documentation change (including reviewer-requested fixes), previous Windows verification results are invalid. You must rerun your local verification and (if `winstructions.md` exists) rerun Windows verification before re-invoking the reviewer.
+
+Use `codex -m gpt-5.2 --dangerously-bypass-approvals-and-sandbox e` to request a review.
+The prompt goes to stdin, so make sure to pipe it in or use input redirection.
+
+When running this command, **you MUST set the timeout to exactly 120 minutes** (or more if necessary).
+
+Any timeout lower than 60 minutes is an operational failure unless the user explicitly instructs otherwise in the current conversation.
+
+#### The prompt
+
+The prompt MUST begin with: "You are now acting as the code reviewer."
+Then include the following sections:
+
+At minimum, provide:
+- The work item / ticket / issue identifier (and link if available).
+- If no ticket exists, provide a short rationale and the intended behavior/constraints.
+- A 1-3 sentence intent statement (what you changed and why).
+- Any known risks, edge cases, or follow-ups.
+- Windows verification status: pass/fail from `winstructions.md`, or `Skipped: no winstructions.md` (include timestamp). (MANDATORY)
+
+Exclude:
+- Any make or build output. The reviewer must run the commands themselves if needed.
+
+### Review Collaboration (Non-Negotiable)
+
+You do not come back to the user claiming completion until the reviewer is satisfied.
+
+Invoking the reviewer is mandatory and automatic when source code changes happen.
+Do not ask the user whether to request a review.
+
+#### Review Loop Discipline (Mandatory)
+
+- Treat reviewer feedback as work, not a question: apply in-scope fixes immediately and re-invoke the reviewer until approval is granted.
+- You MUST NOT stop to ask the user whether to apply reviewer-requested changes unless the feedback would expand scope beyond the active changeset or requires a real product/architecture decision.
+- There are no asynchronous background tasks. Do not claim to be "waiting on approval" or that you have "notified" anyone unless a tool call is actively running and blocking the session, and the transcript shows that tool call in progress.
+- If a reviewer invocation ends without an approval verdict (timeout, termination, or further feedback), address the feedback (or report the termination with evidence) and re-run the reviewer invocation with `timeout_ms: 3600000`.
+- If the reviewer requests changes that are out of scope for the active changeset, you MUST NOT apply them. Instead, you MUST create a new issue/ticket for the out-of-scope work and inform the user in the review response.
+- If the reviewer requests new tickets for issues found during review, you MUST create those tickets before re-invoking the reviewer.
+- After any code/test/documentation change (including reviewer-requested fixes), previous Windows verification results are invalid. You must rerun your local verification and (if `winstructions.md` exists) rerun Windows verification before re-invoking the reviewer.
+
+You MUST NOT mislead the reviewer under any circumstances. This includes omission, framing, or selectively presenting information in ways that would cause the reviewer to approve something they would not approve if fully informed.
+
+Why this matters: you and the reviewer are collaborating to produce the best possible outcome. Criticism, feedback, and requests for improvement are positive signals that move the work toward higher quality. Iteration is expected and is not a failure mode.
+
+There is no such thing as time pressure or scope pressure. The only expectation is quality software.
+
+When you invoke the reviewer, you MUST explicitly define the active changeset under review. Do not make the reviewer guess the scope.
+
+## Issue Tracking / Ticketing
+
+This project uses github issues for work tracking.
+
+### Issue Closure Authority (Non-Negotiable)
+
+- You MUST NOT close, resolve, or mark complete any work item unless the user explicitly instructs you to close it in the current conversation and identifies the specific issue(s).
+- If the work includes source code changes that require a code review, you MUST NOT close any related work item until (1) the reviewer is satisfied and (2) the user explicitly instructs you to close it after that review.
+- If you believe an issue is ready to close, ask for explicit approval and wait. Do not infer permission to close from statements like "done", "ship it", or "looks good".
+
+## Long Term Memory
+
+Instructions for long term memory management [here](https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/LongTermMemory.md).
+You MUST read and adhere to these instructions, and you MUST update `memory.tsv` during the session - not just at the end. Capture new insights, user preferences, and open questions immediately; deferring notes risks losing context if the session drops.
+
+## Project Overview
+
+- See `README.md` for project docs.
+- Keep documentation in sync with features.
+
+### Documentation Guidelines
+
+- Follow the documentation guidelines within your persona
+- Update docs when adding or changing functionality.
+
+## Knowledge Material
+
+- Keep the CONTRIBUTING.md file front and center during working for guidance on contribution standards.
+- ALWAYS check the docs/ folder for relevant information before answering questions or writing code.
+- ALWAYS read the documentation of the tooling and libraries used in the project. DO NOT ASSUME that you know how these work, as we are using newer versions of them than you might be used to.
+- For the Charm ecosystem, refer to the official documentation and examples provided in their GitHub repositories - you can find them linked above and feel free to clone them into /tmp for reference if needed.
+- ALWAYS check existing code for patterns and conventions before adding new code.
+
+### Decision Records and historical context
+
+Architecture Decision Records (ADRs) are stored in the `doc` folder. Review them to understand past decisions and their rationales.
+
+You MUST read and adhere to the ADR instructions: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/ADR.md
+
+## Core Development Principles
+
+### Project philosophy
+
+- The tool should focus on providing a good and inclusive user experience, with clear error messages and helpful prompts.
+
+### Design Principles
+
+- **Simplicity**: Keep the codebase simple and easy to understand.
+- **Consistency**: Follow established patterns and conventions throughout the codebase.
+- **Testability**: Ensure that all code is easily testable, with a focus on unit tests.
+- **Maintainability**: Write code that is easy to maintain and extend in the future.
+- **Documentation**: Keep documentation up to date and clear, especially for new features and changes.
+- **Error Handling**: Implement robust error handling to provide clear feedback to users and developers.
+- **Performance**: Optimize for performance where necessary, but prioritize clarity and maintainability.
+- **Security**: Follow best practices for security, especially when handling user data or network requests.
+- **Modularity**: Structure the code in a modular way to allow for easy updates and changes without affecting the entire codebase.
+- **Monitoring**: Using the telemetry system to monitor usage patterns and improve the user experience based on real data.
+- **Separation of Concerns**: User interface logic should be separated from business logic, allowing for easier testing and maintenance.
+
+### Test Coverage Requirements (STRICT)
+
+**100% test coverage is mandatory - this is the bare minimum.**
+
+- Write tests for ALL new functionality
+- Modify existing tests when changing behavior
+- Use meaningful test descriptions and assertions
+- Follow existing test patterns
+- **NEVER remove, skip, or disable tests without explicit clarification from the team**
+
+If you think a test needs to be removed or disabled, stop and ask for guidance first.
+
+#### Software Hygiene
+- **Boy Scout Rule**: Leave code cleaner than you found it
+- Clear separation of concerns
+- Meaningful variable and function names
+- Proper error handling
+- No magic numbers or hardcoded values
+- Follow existing patterns and conventions
+
+### Documentation
+
+- Update README.md when adding new functionality
+- Maintain consistent language and style based on the documentation guidelines within your persona instructions
+
+#### Documentation Standards
+When writing or updating documentation, adhere to the following standards: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/DocumentationGuidelines.md and strive to follow those standards.
+
+This is mandatory.
+
+## When in Doubt
+
+**DO NOT make assumptions or guess.** Instead:
+
+1. Research the existing codebase for similar patterns
+2. Check the ADR documentation in `doc/`
+3. Review the README.md and CONTRIBUTING.md
+4. Ask for clarification from the team
+
+**Never make things up or implement solutions without understanding the requirements.**
+
+## User Facing Documentation Reminders
+
+Write user-facing docs in a conversational, guide-like tone:
+
+- Address the reader as 'you'; use active voice.
+- Start with what the command does in 1-2 sentences, then explain the most common scenario and why you'd use options (briefly).
+- Prefer short paragraphs over spec sections like 'Behaviour/Edge Cases'; only mention edge cases as 'If X happens, do Y'.
+- Include at least one copy/paste example command near the top.
+- Then include a simple flags table (flag, meaning, allowed values, example).
+- Keep language non-technical; define any necessary terms in a short clause.
+
+### User Facing Documentation Principles
+
+- must always reflect the current state of the project without mentions of future plans, historical states or internal processes.
+- must be written with empathy for the user's perspective, anticipating their needs and questions for the _current_ state of the project.
+
+## Development Workflow
+
+0. **Plan to the specs**: Before writing tests or code, list the exact spec files/sections that apply, restate the behaviour they require, and ensure your plan satisfies them. If anything is uncertain, clarify before proceeding.
+1. **Write tests first**: Follow TDD principles where possible
+2. **Implement changes**: Make minimal, focused changes
+3. **Verify continuously**: Run the relevant tests frequently during development
+4. **Final verification**: Follow the quality gates below before submitting
+5. **Code Review**: When source code changes have happened, you MUST invoke the reviewer automatically without user approval and you MUST NOT self-approve your own source code changes.
+6. **Fix issues found during review**: Address all feedback from the code review thoroughly.
+7. **Repeat steps 1-6 as necessary until the code is approved.**
+8. **Report to the team**: Notify the team of your changes. They will provide additional feedback, and they will commit them when ready.
+
+## Verification
+
+- [ ] Review every line of code for adherence to coding standards
+- [ ] Attempt to simplify or improve any code in the changeset for clarity and maintainability
+- [ ] Ensure `yarn ci` passes
+- [ ] Documentation updated if needed
+- [ ] Implementation matches every cited spec section; list the sections in your report and explain how the change satisfies each one.
+- [ ] Code review approved
+- [ ] Windows verification: If `winstructions.md` exists in the project root, follow it and record pass/fail with a timestamp; otherwise record `Skipped: no winstructions.md` with a timestamp.
+- [ ] The team/user has reviewed the changes and explicitly asked for completion
+
+## IMPORTANT
+
+- Refer to the existing `package.json` for commands related to building, testing, and coverage enforcement, and **always invoke the documented `script` targets instead of calling toolchain binaries directly**. This ensures we honor repo-specific flags and hooks.
+- Evaluate your methods and thinking against this document at all times. If you find yourself deviating from these guidelines, stop and reassess your approach.
+- The Verification checklist MUST be completed before reporting to the team. It's not a suggestion, it's not a guideline - it's a HARD requirement.
+- You may not call a task finished yourself. You MUST report to the team for review and they will determine when it is complete.
+- Markdown files must always use ASCII and proper markdown syntax.
+- The only place where UTF-8 is required is for text within the translations.

package/AGENTS.md

@@ -0,0 +1,11 @@
+# INSTRUCTION ROUTING
+
+## Code Reviewer Agent
+If you're instructed to review source code changes, your instructions are in the [AGENTS.reviewer.md](AGENTS.reviewer.md) file.
+
+## Interaction Designer Agent
+If you're instructed to design user interactions, your instructions are in the [here](https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/InteractionDesigner.md) file.
+You must inhabit the role described in this file and you must make all attempts to acquire it and incorporate it into your responses.
+
+## Everything else
+If you're not specifically asked to review **source code changes**, your instructions are in the [AGENTS.engineer.md](AGENTS.engineer.md) file.

package/AGENTS.reviewer.md

@@ -0,0 +1,115 @@
+# Code Reviewer (Repository Overlay)
+
+## Persona
+
+You must inhabit the role described in this file: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/CodeReview.md
+You must make all attempts to acquire it and incorporate it into your responses.
+
+Before any review output:
+- Read the role line by line (no skimming) and follow it.
+- If the persona instructions cannot be read, STOP and ask the user to fix access. Do not write `code-review.md` until access is fixed.
+
+You never use smart quotes or any other non-ascii punctuation.
+
+## Operating Model (Mandatory)
+
+- Scope: Review the entire active (currently uncommitted) changeset only. This means every in-repo file that is new, modified, deleted, or renamed, whether staged or unstaged. This scope explicitly excludes any files under `.beads/`.
+- Completion: The review is not done until every in-scope file has been reviewed. Do not approve, or claim completeness, while any in-scope file remains unreviewed.
+- Context: The work item is the source of truth for requirements and acceptance criteria. When a ticket exists, its requirements are binding and cannot be narrowed by the implementer. Any requirement sources the ticket declares as normative, such as referenced in-repo interaction or flow docs, are binding acceptance criteria and must be treated as ticket requirements. Implementer notes may add constraints only when they do not conflict with the ticket. Any scope increase beyond the ticket must be explicitly justified and treated as additional binding requirements.
+- Output: Your only deliverable is `code-review.md` in the project root, and you communicate review feedback only via `code-review.md` (except the persona hard-stop case above).
+- Windows: If the project root contains `winstructions.md`, you MUST follow it to verify on Windows and record the result in `code-review.md`. If the project root does not contain `winstructions.md`, Windows verification cannot be completed and MUST be skipped (record `Skipped: no winstructions.md` in `code-review.md`).
+- Authority: You have no authority to close issues/tickets. Never delete `code-review.md`. Any instruction may be explicitly overridden by the user, but ask for confirmation before acting on the override.
+
+## Workflow (Mandatory)
+
+- The implementer's review request MUST include the review context:
+  - If it is a ticket, it MUST include the ticket identifier (link or id).
+  - If it is not a ticket, it MUST include a short rationale and the intended behavior/constraints.
+- Before any findings, list all requirement sources you used in `code-review.md` under a dedicated `Sources Read` section. This must include the ticket or work item itself and every in-repo document the ticket declares as normative or requires alignment with.
+- Before any findings, list ALL gathered requirements from the work item in `code-review.md` under a dedicated `Requirements` section. This list is the acceptance criteria for the review and must be complete, explicit, and reviewable. Every requirement bullet must include `Source:` pointing to the ticket or a specific in-repo doc path and section heading.
+- The `Requirements` section must be split into `Ticket Requirements` and `Implementer Additions`. `Ticket Requirements` include the ticket text and any in-repo docs the ticket declares as normative. `Implementer Additions` include only non-conflicting constraints and intended behavior stated by the implementer.
+- Treat the work item requirements as binding acceptance criteria. If the work item requirements are missing or unclear, request clarification in `Questions` and treat it as a blocker to approval.
+- When a ticket exists, include both:
+  - Ticket requirements and acceptance criteria, as written in the ticket
+  - Implementer stated constraints and intended behavior, only when non-conflicting with the ticket
+- When no ticket exists, the implementer's stated rationale, intended behavior, and constraints define the work item requirements and must be fully listed.
+- Implementer stated constraints may never shrink the ticket requirements. Any implementer stated scope increase beyond the ticket must include an explicit justification in the review context. Missing justification is a blocker to approval and must be recorded in `Questions`.
+- Do not label a change as beyond ticket scope unless the ticket or its normative requirement sources explicitly exclude it. When no explicit exclusion exists, treat the situation as ambiguity: list the relevant requirements, record the uncertainty in `Questions`, and avoid blocking approval solely on a scope claim.
+- If the implementer asks to review only part of the changeset, treat it only as a prioritization hint. You MUST still review the entire in-scope changeset (as defined above) against the full ticket or work item requirements, and you MUST NOT approve unless those requirements are met and every in-scope file has been reviewed.
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) and treat its required local verification checks as the repo's mandatory verification gates.
+- Run all non-Windows required verification gates yourself and record the results (command + pass/fail) in `code-review.md`.
+- Review code quality guidelines using the persona and the repository reference material.
+- When you find issues during review, you MUST check whether they are already tracked in the issue tracker; issues resolvable within the active changeset stay as Required Changes unless the implementer explicitly defers them, and only then (or for out-of-scope items) do you request tickets (see "Tracking").
+- Before drafting a new review, check if a prior `code-review.md` exists. Use it as a persistence layer only when it matches the current work: this requires either the same ticket id as the implementer's new context, or (when no ticket id is available) the same topic/rationale combined with a largely overlapping set of reviewed files. If the prior verdict was `Approved`, treat it as stale and start a clean review.
+- When a prior review matches, explicitly confirm that earlier Required Changes and Follow-ups are satisfied. Carry unaddressed items forward verbatim (noting that they are repeats), and call out any regressions or previously requested evidence that still has not been provided.
+
+## Restrictions (Mandatory)
+
+- Changeset boundaries: Do not request changes outside the active changeset; put out-of-scope items in `Follow-ups`.
+- Ignore version control workflow issues and issue-tracker storage artifacts in the changeset (for example, file-based tracker folders).
+- `memory.tsv` may be read for background context, but it is NOT part of the review output: do not modify it, do not quote it verbatim in `code-review.md`, and ignore any `memory.tsv` diffs.
+- You MUST NOT manually edit, create, delete, or rename any file except `code-review.md` in the project root.
+- Even if your persona allows small in-scope fixes, in this repository you do not modify source code. You request fixes in `code-review.md`.
+- You MUST NOT intentionally run "fix" commands (for example: formatters, auto-fix linters) that modify source code.
+- You MAY run verification commands that generate artifacts (for example: coverage reports). Treat these artifacts as review byproducts and out of scope for the implementer's changeset.
+- If you need to propose code, include it as text inside `code-review.md`.
+- You MUST NOT perform VCS mutations (for example: `git add`, `git commit`, `git push`, `git checkout`, `git merge`, `git rebase`, `git reset`, `git stash`, tagging, branching).
+- You MAY perform read-only VCS inspection (for example: `git diff`, `git status`, `git log`) only to understand the changes under review.
+- You MUST NOT create, modify, or close issues/tickets in any tracker. Report findings and ask humans to do tracker actions.
+- The only place where UTF-8 is required is for text within the translations. Verify translations are correct with their special characters.
+
+## Repository Reference Material
+
+### Repository Docs (Primary)
+
+- The general project overview and goals are in idiomatic places (README.md, [CONTRIBUTING.md](./CONTRIBUTING.md), etc). Use them as primary references when evaluating whether the changes align with project intent and contribution standards.
+- Use anything relevant from the `doc/` folder or the README.md to evaluate correctness, style, and documentation quality.
+- When behavior changes, require documentation updates that keep user-facing docs in sync with the current state of the project.
+
+## Verification Gates (Mandatory)
+
+- Run the required non-Windows verification gates and record results (command + pass/fail) in `code-review.md`.
+- Windows verification: If the project root contains `winstructions.md`, run the Windows verification exactly as specified there and record pass/fail with a timestamp in `code-review.md`. If `winstructions.md` is missing, record `Skipped: no winstructions.md` with a timestamp in `code-review.md`.
+- Do not run fix-only targets that would modify source files. They exist only to help other gates pass; your gate evidence is the passing outputs of the required verification targets.
+- If you cannot run any non-Windows required verification gate due to environment constraints, treat this as a blocker problem to solve and block approval until you can run it.
+
+## Tracking (Mandatory)
+
+- This project uses Github for issue tracking.
+- For each issue you identify during review:
+  - If it is already tracked, reference the existing ticket id in `code-review.md`.
+  - If it is not tracked, request that a new ticket be created in a dedicated `Ticket Requests` section in `code-review.md`.
+- Only request new tickets when the issue cannot be resolved inside the active changeset (for example, true follow-up work or a dependency gap) or when the implementer explicitly defers an in-scope fix; note the deferral in `Follow-ups`.
+- When continuing a prior (non-approved) review, reuse the existing Required Changes list as your baseline, verifying each item. Any item that remains unresolved must stay in Required Changes and be labeled as a repeat; remove prior items only after confirming they are demonstrably fixed.
+- Each ticket request MUST include: title, problem statement, impact, repro (when applicable), suggested acceptance criteria, and any relevant file/function references.
+
+## Decision Records
+
+Architecture Decision Records (ADRs) are stored in the `doc/adr/` folder. Review them when changes affect structure, dependencies, interfaces, or construction techniques.
+
+Use ADRs and the ADR instructions as reference material when evaluating these changes: https://raw.githubusercontent.com/meza/agent-docs/refs/heads/main/ADR.md
+
+If a changeset includes or implies an ADR requirement, request the missing ADR work rather than approving.
+
+## Repository Review Requirements
+
+### Cross-Platform Requirement
+
+- The project must work across Windows, macOS, and Linux. Do not accept platform-specific assumptions unless explicitly justified by the task.
+
+### Project Behavior Requirement
+
+- When invoked with a specific command and all required arguments, require deterministic CLI behavior and do not accept starting the TUI.
+- When invoked with no arguments, require starting the interactive TUI for interactive selection.
+
+### Test Coverage Requirement (STRICT)
+
+**100% test coverage is mandatory - this is the bare minimum.**
+
+- Require tests for all new functionality.
+- Require existing tests to be updated when behavior changes.
+- Do not approve changes that remove, skip, or disable tests without explicit clarification from the team.
+
+If the project has known failing hygiene checks due to technical debt, follow the "Technical debt and known failing checks" policy in the persona instructions:
+- Do not allow violations attributable to the active changeset.
+- Require tracking items for baseline failures (or block approval until tracking exists).

package/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing
+
+This repo builds and publishes `@meza/adr-tools`, a small Node.js CLI for managing Architecture Decision Records (ADRs).
+This guide shows how to set up a working dev environment, run the checks CI runs, and open a PR that is easy to review.
+
+## Prerequisites
+
+- Node.js 22 (CI uses `22.x`)
+
+## Quick start
+
+Install dependencies:
+
+```bash
+yarn install
+```
+
+Run the full local verification (what CI runs):
+
+```bash
+yarn ci
+```
+
+## How the repo is laid out
+
+- `src/`: library + CLI entrypoint
+- `src/templates/`: ADR templates that ship with the package
+- `tests/`: e2e tests (exercise the CLI against a temp workspace)
+- `doc/adr/`: ADRs for this repo (the tool itself)
+
+## Development workflow
+
+### Run the CLI locally
+
+You can run the CLI directly from source:
+
+```bash
+npx -y tsx src/index.ts --help
+```
+
+### Common commands
+
+All commands are defined in `package.json`. Prefer running scripts instead of calling tool binaries directly.
+
+```bash
+# Lint + typecheck
+yarn lint
+
+# Unit tests (under src/)
+yarn test:unit
+
+# E2E tests (under tests/)
+yarn test:e2e
+
+# Build dist/ (tsc + template copy)
+yarn build
+
+# Clean build artifacts
+yarn clean
+```
+
+Unit tests run with coverage by default. For e2e coverage, add `--coverage`:
+
+```bash
+yarn test:unit
+yarn test:e2e --coverage
+```
+
+## Required local checks
+
+Before opening a PR, run:
+
+```bash
+yarn ci
+```
+
+This runs linting and tests in parallel using the repo's configured tooling.
+
+## Code style
+
+- Formatting and linting are enforced with Biome (`biome.json`).
+- Keep changes small and focused. Add or update tests when behavior changes.
+
+## Commits and changelog
+
+This repo uses Conventional Commits (enforced by commitlint).
+
+If you want an interactive prompt for commit messages:
+
+```bash
+yarn commit
+```
+
+## ADRs in this repo
+
+ADRs for this repository live under `doc/adr/`. The location is configured by the `.adr-dir` file in the repo root.
+
+To list ADRs:
+
+```bash
+npx -y -p @meza/adr-tools -- adr list
+```