libar-dev · darko-mijic · Feb 22, 2026 · Feb 21, 2026 · Feb 21, 2026 · Feb 21, 2026
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
@@ -160,7 +160,6 @@ knowledge_base:
     enabled: true
     filePatterns:
       - '**/CLAUDE.md'
-      - '**/INSTRUCTIONS.md'
 
   learnings:
     scope: local # Keep learnings repository-specific

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,38 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+labels: bug
+---
+
+## Describe the Bug
+
+A clear description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Run `...`
+2. With config `...`
+3. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Error Output
+
+```text
+Paste any error messages or unexpected output here.
+```
+
+## Environment
+
+- **Node.js version:** (e.g., 20.10.0)
+- **Package version:** (e.g., 1.0.0-pre.0)
+- **OS:** (e.g., macOS 15, Ubuntu 24.04)
+- **Package manager:** (npm / pnpm / yarn)
+
+## Additional Context
+
+Any other context — config files, feature files, annotation examples — that helps explain the problem.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,21 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+## Is your feature request related to a problem?
+
+A clear description of the problem. Ex. "I'm always frustrated when..."
+
+## Describe the Solution You'd Like
+
+A clear description of what you want to happen.
+
+## Describe Alternatives You've Considered
+
+Any alternative solutions or features you've considered.
+
+## Additional Context
+
+Any other context — use cases, examples, screenshots — that helps explain the request.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -49,6 +49,4 @@ jobs:
       - name: Test
         run: pnpm test
 
-  # Note: verify-dist check removed due to non-deterministic TypeScript
-  # declaration file ordering between macOS and Ubuntu builds.
-  # The dist/ is rebuilt during test jobs and tests verify correctness.
+  # dist/ is not tracked in git — built fresh during CI and publish workflows.
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,8 @@
 # Dependencies
 node_modules/
 
-# Build cache (but NOT dist/ - needed for git dependencies)
+# Build output
+dist/
 *.tsbuildinfo
 
 # IDE

diff --git a/.husky/pre-push b/.husky/pre-push
@@ -3,22 +3,4 @@ set -e
 echo "Running tests..."
 pnpm test
 
-echo "Building dist/..."
-pnpm build
-
-# Check if dist/ has uncommitted changes after build
-if ! git diff --quiet dist/; then
-  echo ""
-  echo "ERROR: dist/ is out of sync with source code!"
-  echo ""
-  echo "The build produced changes in dist/. Please commit them:"
-  git diff --stat dist/
-  echo ""
-  echo "Run these commands to fix:"
-  echo "  git add dist/"
-  echo "  git commit --amend --no-edit"
-  echo ""
-  exit 1
-fi
-
 echo "All checks passed!"
diff --git a/.npmrc b/.npmrc
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,197 @@
+# AGENTS.md
+
+This file helps future Codex sessions ramp up quickly in this repository.
+
+## Project Identity
+
+- Package: `@libar-dev/delivery-process`
+- Purpose: context engineering toolkit that extracts patterns from TypeScript + Gherkin into a queryable delivery state, generated docs, and workflow enforcement.
+- Core principle: code/spec annotations are the source of truth; generated docs are projections.
+
+## Where To Read First
+
+1. Manual docs index: `/Users/darkomijic/dev-projects/delivery-process/docs/INDEX.md`
+2. Config entry point: `/Users/darkomijic/dev-projects/delivery-process/delivery-process.config.ts`
+3. Live generated area index: `/Users/darkomijic/dev-projects/delivery-process/docs-live/PRODUCT-AREAS.md`
+4. Key generated area docs:
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/ANNOTATION.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CONFIGURATION.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CORE-TYPES.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/DATA-API.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/GENERATION.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/PROCESS.md`
+   - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/VALIDATION.md`
+
+## Onboarding Context (Tutorial WIP)
+
+- External tutorial source: `/Users/darkomijic/dev-projects/delivery-process-tutorials/TUTORIAL-ARTICLE-v1.md`
+- Tutorial goal: bootstrap from blank project to full docs/query flow (`11 patterns`, `26 generated files` in demo scenario).
+- Treat tutorial outputs as illustrative; validate commands against current CLI behavior before codemods/docs changes.
+- Important known alignment points from tutorial review:
+  - `process-api overview` includes the Data API helper section in output (not always shown in article snippets).
+  - Current `generate-docs --list-generators` output does not include `product-area-docs`.
+  - `generate-docs` accepts both repeated `-g` flags and comma-separated generator lists.
+  - Shape-derived entries can affect counts and `stubs` output (shape patterns appear as separate entries).
+  - `arch context` groups only patterns carrying explicit `@libar-docs-arch-context`.
+
+## Consumer Repo Setup Conventions
+
+When guiding users in external repos, pick command style based on config format:
+
+- If the repo uses `delivery-process.config.js` (or no config), package binaries are fine:
+
+```bash
+npx generate-docs --help
+npx process-api --help
+npx lint-patterns --help
+npx lint-process --help
+npx validate-patterns --help
+```
+
+- If the repo uses `delivery-process.config.ts`, use `tsx`-based wrappers (or switch to `.js` config).
+  - Reason: plain Node execution may fail to import `.ts` config files in some environments.
+
+Use `delivery-process.config.ts` or `.js` as the main integration contract and keep scripts thin wrappers around package CLIs.
+
+## Architecture Snapshot
+
+- Pipeline: `Config -> Scanner -> Extractor -> Transformer -> Codec`.
+- Central read model: `MasterDataset` (consumed by docs generation, Data API, and validators).
+- Preset in this repo config: `libar-generic` (`@libar-docs-*` tags).
+- Source ownership invariant:
+  - TypeScript owns runtime relationships (`uses`, `used-by`, category-like tags).
+  - Gherkin owns planning/process metadata (`depends-on`, quarter, team, phase, deliverables).
+
+## Repository Map
+
+- Source code: `/Users/darkomijic/dev-projects/delivery-process/src`
+- Feature specs (roadmap/process/decisions/releases):
+  - `/Users/darkomijic/dev-projects/delivery-process/delivery-process/specs`
+  - `/Users/darkomijic/dev-projects/delivery-process/delivery-process/decisions`
+  - `/Users/darkomijic/dev-projects/delivery-process/delivery-process/releases`
+- Design stubs (non-compiled on purpose): `/Users/darkomijic/dev-projects/delivery-process/delivery-process/stubs`
+- Tests:
+  - Feature files: `/Users/darkomijic/dev-projects/delivery-process/tests/features`
+  - Step definitions: `/Users/darkomijic/dev-projects/delivery-process/tests/steps`
+
+## Session Workflow (Project Convention)
+
+Session types and expected outcomes:
+
+1. Planning: create/update roadmap `.feature` spec (status typically `roadmap`).
+2. Design: produce decision specs and/or stubs in `delivery-process/stubs/` (no implementation).
+3. Implementation: transition `roadmap -> active -> completed` while implementing deliverables.
+
+FSM/protection conventions:
+
+- `roadmap` / `deferred`: fully editable
+- `active`: scope-locked (do not add deliverables)
+- `completed`: hard-locked (changes require unlock-reason tag)
+
+## Data API First (Preferred Discovery Path)
+
+Use the CLI instead of broad file exploration whenever possible:
+
+```bash
+pnpm process:query -- overview
+pnpm process:query -- scope-validate <PatternName> implement
+pnpm process:query -- context <PatternName> --session implement
+pnpm process:query -- dep-tree <PatternName>
+pnpm process:query -- files <PatternName> --related
+```
+
+Useful discovery commands:
+
+```bash
+pnpm process:query -- list --status roadmap --names-only
+pnpm process:query -- arch blocking
+pnpm process:query -- stubs --unresolved
+pnpm process:query -- unannotated --path src
+```
+
+## Build, Test, Validation Commands
+
+Core dev:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+Process/quality checks:
+
+```bash
+pnpm lint:steps
+pnpm lint-patterns
+pnpm lint:process
+pnpm validate:patterns
+pnpm validate:dod
+pnpm validate:all
+```
+
+## Docs Generation
+
+- Main generated output root from config: `docs-generated/`
+- Product area and ADR outputs are overridden to `docs-live/` in config.
+
+Common commands:
+
+```bash
+pnpm docs:product-areas
+pnpm docs:reference
+pnpm docs:decisions
+pnpm docs:all
+```
+
+Rule: do not hand-edit generated artifacts when regeneration is the intended flow.
+
+Current built-in generator list is discovered from CLI (`generate-docs --list-generators`).
+Do not assume undocumented generator names are available without checking.
+
+## Testing Rules (Important)
+
+- This repo follows strict Gherkin-first testing:
+  - Specs in `.feature`
+  - Step definitions in `.steps.ts`
+  - Avoid introducing classic `*.test.ts` files for new coverage unless explicitly requested.
+- Never commit skipped/only tests (`it.skip`, `it.only`, `describe.skip`, `describe.only`).
+- For `vitest-cucumber`:
+  - `Scenario`: use Cucumber expressions (`{string}`, `{int}`) and function params.
+  - `ScenarioOutline`: use `<column>` placeholders and read via `variables.column`.
+
+## Change Hygiene
+
+- Keep edits focused; prefer changing source-of-truth files over generated docs.
+- If changing tags/taxonomy/config, run relevant validation and at least targeted docs generation.
+- For workflow/status/deliverable changes, run process guard checks before finalizing.
+
+## Practical Start Checklist For New Sessions
+
+1. Read `docs/INDEX.md` and `delivery-process.config.ts`.
+2. Run `pnpm process:query -- overview`.
+3. If working on a specific pattern, run:
+   - `pnpm process:query -- scope-validate <PatternName> implement`
+   - `pnpm process:query -- context <PatternName> --session <design|implement>`
+4. Make minimal source changes.
+5. Run targeted tests + relevant lint/validation.
+6. Regenerate docs if source annotations/specs/config changed.
+
+## Future Enhancement Candidate: Interactive Init CLI
+
+There is currently no dedicated interactive onboarding command in this package.
+If implementing one, design for existing-repo adoption first:
+
+1. Command shape
+   - Add a new bin command (example: `delivery-process-init`) so users can run `npx delivery-process-init`.
+2. Wizard responsibilities
+   - Detect package manager and module mode (`type: module`).
+   - Scaffold `delivery-process.config.ts` with chosen preset and discovered source globs.
+   - Offer optional npm scripts for `process-api`, docs generation, and validation commands.
+   - Optionally scaffold starter folders (`delivery-process/specs`, `delivery-process/stubs`) and sample spec/stub templates.
+3. Safety requirements
+   - Dry-run mode and explicit overwrite confirmations.
+   - Never silently overwrite existing `delivery-process.config.ts` or user scripts.
+4. Success criteria
+   - User can run `process-api overview` and `generate-docs --list-generators` immediately after setup.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-pre.0] - 2026-02-21
+
+First npm-published pre-release for monorepo validation.
+
+### Added
+
+- Stable public API with 12 subpath exports (including new `./api`)
+- Process Data API with 27 CLI subcommands for AI-native delivery state queries
+- FSM-enforced workflow validation via pre-commit hooks
+- Codec-based document generation (patterns, roadmap, decisions, product areas, etc.)
+- Cross-source validation (TypeScript + Gherkin dual-source merging)
+- MasterDataset single read model (ADR-006)
+
+### Changed
+
+- Published to npm registry (previously consumed via `git+https://` only)
+- `dist/` removed from git tracking -- built fresh during publish
+- `@libar-dev/modular-claude-md` moved from dependencies to devDependencies
+- Package size trimmed (removed self-referential docs from tarball)
+
+[Unreleased]: https://github.com/libar-dev/delivery-process/compare/v1.0.0-pre.0...HEAD
+[1.0.0-pre.0]: https://github.com/libar-dev/delivery-process/releases/tag/v1.0.0-pre.0