@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/skills/static/git-conventions.md

@@ -1,227 +1,227 @@
-# Git Conventions
-
-> Clean history is documentation. Every commit tells a story. Make it worth reading.
-
----
-
-## Conventional Commits — format
-
-```
-<type>(<scope>): <subject>
-
-[optional body]
-
-[optional footer]
-```
-
-### Types
-
-| Type | When to use |
-|---|---|
-| `feat` | New feature or capability |
-| `fix` | Bug fix |
-| `docs` | Documentation only |
-| `style` | Formatting, whitespace — no logic change |
-| `refactor` | Code restructuring — no feature/fix |
-| `perf` | Performance improvement |
-| `test` | Adding or fixing tests |
-| `chore` | Build process, dependencies, tooling |
-| `ci` | CI configuration |
-| `revert` | Reverts a previous commit |
-
-### Scope (optional but recommended)
-
-Use the affected module, layer, or feature: `auth`, `appointments`, `billing`, `api`, `ui`, `db`.
-
----
-
-## Commit message examples
-
-```bash
-# Good — specific, uses type + scope
-feat(appointments): add conflict detection when booking same doctor
-
-fix(auth): redirect to intended URL after login
-
-docs(api): add Postman collection for appointments endpoints
-
-refactor(billing): extract InvoiceCalculator from OrderService
-
-test(appointments): add edge cases for past-date booking validation
-
-chore(deps): bump laravel/framework to 11.3.0
-
-perf(db): add index on appointments(doctor_id, date)
-
-ci(release): skip npm publish when version already exists
-```
-
-```bash
-# Bad — no context, no type
-git commit -m "fix bug"
-git commit -m "changes"
-git commit -m "WIP"
-git commit -m "update stuff"
-```
-
----
-
-## Subject line rules
-
-- Imperative mood: "add", "fix", "remove" — not "added", "fixed", "removes"
-- No period at the end
-- Max 72 characters
-- If you can't describe it in 72 chars, the commit is too large — split it
-
----
-
-## Commit body (when needed)
-
-Use the body to explain **why**, not **what**. The diff shows what changed.
-
-```
-fix(appointments): prevent double-booking under concurrent requests
-
-Without a database-level lock, two simultaneous booking requests for the
-same doctor+timeslot could both pass the in-memory conflict check and
-create duplicate appointments.
-
-Added SELECT ... FOR UPDATE to the conflict check query to serialize
-concurrent writes at the database level.
-
-Closes #142
-```
-
----
-
-## Branching strategy
-
-### Git Flow (default for projects with releases)
-
-```
-main          ← production, protected, tagged releases only
-develop       ← integration branch, latest stable work
-feature/*     ← new features (branch from develop)
-fix/*         ← bug fixes (branch from develop or main)
-release/*     ← release preparation (branch from develop)
-hotfix/*      ← urgent production fixes (branch from main)
-```
-
-### GitHub Flow (simpler, for continuous deployment)
-
-```
-main          ← always deployable, protected
-feature/*     ← short-lived feature branches (branch from main)
-fix/*         ← short-lived fix branches (branch from main)
-```
-
-**Use GitHub Flow** for small/medium teams shipping continuously. Use Git Flow when maintaining multiple versions.
-
----
-
-## Branch naming
-
-```bash
-feature/appointment-conflict-detection
-feature/stripe-billing-integration
-fix/login-redirect-loop
-fix/n1-query-appointments-index
-hotfix/production-500-on-checkout
-chore/upgrade-laravel-11
-docs/add-api-postman-collection
-```
-
----
-
-## Pull Request conventions
-
-**Title:** same format as a commit message — `type(scope): subject`
-
-**Description template:**
-```markdown
-## What
-Brief description of the change.
-
-## Why
-Context — what problem does this solve? Link issues.
-
-## How
-Key technical decisions made. Alternatives considered.
-
-## Test plan
-- [ ] Manual steps to verify the change
-- [ ] Automated tests added/updated
-
-## Screenshots (if UI change)
-```
-
----
-
-## Tagging and releases
-
-```bash
-# Semantic versioning: MAJOR.MINOR.PATCH
-git tag -a v1.2.3 -m "Release v1.2.3"
-git push origin v1.2.3
-
-# MAJOR — breaking changes
-# MINOR — new backwards-compatible features
-# PATCH — bug fixes
-```
-
----
-
-## Protecting shared history
-
-```bash
-# NEVER force push to shared branches
-git push --force origin main   # FORBIDDEN
-
-# Rebase private branches before merging (keep history clean)
-git checkout feature/my-feature
-git rebase develop
-
-# Squash noisy WIP commits before PR
-git rebase -i develop   # interactive rebase
-```
-
----
-
-## Useful git commands
-
-```bash
-# See what changed in last commit
-git show --stat
-
-# Amend last commit message (before push only)
-git commit --amend -m "fix(auth): correct redirect target"
-
-# Stash uncommitted changes
-git stash push -m "WIP: appointment form validation"
-git stash pop
-
-# Find which commit introduced a bug
-git bisect start
-git bisect bad HEAD
-git bisect good v1.1.0
-
-# Clean untracked files (dry run first)
-git clean -n   # preview
-git clean -fd  # execute
-```
-
----
-
-## ALWAYS
-- Write imperative, specific commit messages
-- One logical change per commit
-- Branch from the correct base (`main` or `develop`)
-- Rebase feature branches before merging
-- Tag releases with semantic versions
-
-## NEVER
-- Force push to `main` or `develop`
-- Commit secrets, `.env` files, or credentials
-- Use generic messages ("fix", "update", "changes")
-- Commit commented-out code — delete it instead
-- Leave WIP commits in a PR — squash or amend before review
+# Git Conventions
+
+> Clean history is documentation. Every commit tells a story. Make it worth reading.
+
+---
+
+## Conventional Commits — format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace — no logic change |
+| `refactor` | Code restructuring — no feature/fix |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+| `chore` | Build process, dependencies, tooling |
+| `ci` | CI configuration |
+| `revert` | Reverts a previous commit |
+
+### Scope (optional but recommended)
+
+Use the affected module, layer, or feature: `auth`, `appointments`, `billing`, `api`, `ui`, `db`.
+
+---
+
+## Commit message examples
+
+```bash
+# Good — specific, uses type + scope
+feat(appointments): add conflict detection when booking same doctor
+
+fix(auth): redirect to intended URL after login
+
+docs(api): add Postman collection for appointments endpoints
+
+refactor(billing): extract InvoiceCalculator from OrderService
+
+test(appointments): add edge cases for past-date booking validation
+
+chore(deps): bump laravel/framework to 11.3.0
+
+perf(db): add index on appointments(doctor_id, date)
+
+ci(release): skip npm publish when version already exists
+```
+
+```bash
+# Bad — no context, no type
+git commit -m "fix bug"
+git commit -m "changes"
+git commit -m "WIP"
+git commit -m "update stuff"
+```
+
+---
+
+## Subject line rules
+
+- Imperative mood: "add", "fix", "remove" — not "added", "fixed", "removes"
+- No period at the end
+- Max 72 characters
+- If you can't describe it in 72 chars, the commit is too large — split it
+
+---
+
+## Commit body (when needed)
+
+Use the body to explain **why**, not **what**. The diff shows what changed.
+
+```
+fix(appointments): prevent double-booking under concurrent requests
+
+Without a database-level lock, two simultaneous booking requests for the
+same doctor+timeslot could both pass the in-memory conflict check and
+create duplicate appointments.
+
+Added SELECT ... FOR UPDATE to the conflict check query to serialize
+concurrent writes at the database level.
+
+Closes #142
+```
+
+---
+
+## Branching strategy
+
+### Git Flow (default for projects with releases)
+
+```
+main          ← production, protected, tagged releases only
+develop       ← integration branch, latest stable work
+feature/*     ← new features (branch from develop)
+fix/*         ← bug fixes (branch from develop or main)
+release/*     ← release preparation (branch from develop)
+hotfix/*      ← urgent production fixes (branch from main)
+```
+
+### GitHub Flow (simpler, for continuous deployment)
+
+```
+main          ← always deployable, protected
+feature/*     ← short-lived feature branches (branch from main)
+fix/*         ← short-lived fix branches (branch from main)
+```
+
+**Use GitHub Flow** for small/medium teams shipping continuously. Use Git Flow when maintaining multiple versions.
+
+---
+
+## Branch naming
+
+```bash
+feature/appointment-conflict-detection
+feature/stripe-billing-integration
+fix/login-redirect-loop
+fix/n1-query-appointments-index
+hotfix/production-500-on-checkout
+chore/upgrade-laravel-11
+docs/add-api-postman-collection
+```
+
+---
+
+## Pull Request conventions
+
+**Title:** same format as a commit message — `type(scope): subject`
+
+**Description template:**
+```markdown
+## What
+Brief description of the change.
+
+## Why
+Context — what problem does this solve? Link issues.
+
+## How
+Key technical decisions made. Alternatives considered.
+
+## Test plan
+- [ ] Manual steps to verify the change
+- [ ] Automated tests added/updated
+
+## Screenshots (if UI change)
+```
+
+---
+
+## Tagging and releases
+
+```bash
+# Semantic versioning: MAJOR.MINOR.PATCH
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# MAJOR — breaking changes
+# MINOR — new backwards-compatible features
+# PATCH — bug fixes
+```
+
+---
+
+## Protecting shared history
+
+```bash
+# NEVER force push to shared branches
+git push --force origin main   # FORBIDDEN
+
+# Rebase private branches before merging (keep history clean)
+git checkout feature/my-feature
+git rebase develop
+
+# Squash noisy WIP commits before PR
+git rebase -i develop   # interactive rebase
+```
+
+---
+
+## Useful git commands
+
+```bash
+# See what changed in last commit
+git show --stat
+
+# Amend last commit message (before push only)
+git commit --amend -m "fix(auth): correct redirect target"
+
+# Stash uncommitted changes
+git stash push -m "WIP: appointment form validation"
+git stash pop
+
+# Find which commit introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good v1.1.0
+
+# Clean untracked files (dry run first)
+git clean -n   # preview
+git clean -fd  # execute
+```
+
+---
+
+## ALWAYS
+- Write imperative, specific commit messages
+- One logical change per commit
+- Branch from the correct base (`main` or `develop`)
+- Rebase feature branches before merging
+- Tag releases with semantic versions
+
+## NEVER
+- Force push to `main` or `develop`
+- Commit secrets, `.env` files, or credentials
+- Use generic messages ("fix", "update", "changes")
+- Commit commented-out code — delete it instead
+- Leave WIP commits in a PR — squash or amend before review

package/template/.aioson/skills/static/git-worktrees.md

@@ -1,36 +1,36 @@
-# Git Worktrees — Isolated Development
-
-> Optional but recommended for SMALL/MEDIUM feature work.
-> Keeps main branch clean while you develop.
-
-## When to use
-- Starting implementation of a new feature branch
-- When you want to be able to discard work safely
-- When you need to switch context between features
-
-## Quick setup
-```bash
-# Create worktree for feature
-git worktree add ../project-feature-name -b feature/name
-
-# Work in the worktree
-cd ../project-feature-name
-# ... install deps, run setup ...
-
-# When done: merge or discard
-git worktree remove ../project-feature-name
-```
-
-## Safety rule
-The worktrees directory must be in `.gitignore`.
-Add before creating:
-```bash
-echo ".worktrees/" >> .gitignore
-git add .gitignore && git commit -m "chore: add worktrees to gitignore"
-```
-
-## Finish options
-1. Merge back to main locally
-2. Push and create PR
-3. Keep branch as-is (continue later)
-4. Discard (requires typing "discard" to confirm)
+# Git Worktrees — Isolated Development
+
+> Optional but recommended for SMALL/MEDIUM feature work.
+> Keeps main branch clean while you develop.
+
+## When to use
+- Starting implementation of a new feature branch
+- When you want to be able to discard work safely
+- When you need to switch context between features
+
+## Quick setup
+```bash
+# Create worktree for feature
+git worktree add ../project-feature-name -b feature/name
+
+# Work in the worktree
+cd ../project-feature-name
+# ... install deps, run setup ...
+
+# When done: merge or discard
+git worktree remove ../project-feature-name
+```
+
+## Safety rule
+The worktrees directory must be in `.gitignore`.
+Add before creating:
+```bash
+echo ".worktrees/" >> .gitignore
+git add .gitignore && git commit -m "chore: add worktrees to gitignore"
+```
+
+## Finish options
+1. Merge back to main locally
+2. Push and create PR
+3. Keep branch as-is (continue later)
+4. Discard (requires typing "discard" to confirm)

package/template/.aioson/skills/static/harness-sensors.md

@@ -1,74 +1,74 @@
-# Harness Sensors — Post-Action Verification
-
-> Load this when you need to verify that agent actions comply with project constraints.
-> Sensors run AFTER the action, not before (that's what guides/gates do).
-
-## When to run sensors
-
-| Trigger | Sensor | Agent |
-|---------|--------|-------|
-| After commit | Rule compliance check | @dev, @deyvin |
-| After spec update | Drift detection vs requirements | @dev, @analyst |
-| After architecture.md written | Constitution compliance | @architect |
-| After feature closure | AC coverage verification | @qa |
-| After session end | Context budget report | All agents |
-
-## Sensor 1 — Rule compliance check
-
-After every commit, verify:
-1. Read all `.md` files in `.aioson/rules/`
-2. For each rule, check if the committed files violate any stated convention
-3. If violation found: do not revert — log warning and continue
-4. Write violations to `project-pulse.md` under "Blockers" if severity is high
-
-**Implementation:** This sensor is agent-internal (instruction-based), not a CLI hook.
-The agent instruction says: "after committing, re-read the rules and verify your commit complies."
-
-## Sensor 2 — Spec drift check
-
-After updating `spec-{slug}.md`:
-1. Compare `requirements-{slug}.md` AC list with `spec-{slug}.md` "Edge cases handled" section
-2. If ACs exist in requirements that are not mentioned in spec: flag as potential drift
-3. Write flagged items to `pending_review` in spec frontmatter
-
-## Sensor 3 — Constitution compliance (architecture)
-
-After writing `architecture.md`:
-1. Read `constitution.md`
-2. For each article, verify:
-   - Article I: Is there a spec artifact that preceded this architecture?
-   - Article II: Is the architecture depth proportional to classification?
-   - Article VI: Does the architecture introduce unnecessary layers?
-3. Self-report: add `## Constitution check` section at end of `architecture.md`
-
-## Sensor 4 — AC coverage verification
-
-After @qa writes its report:
-1. Count ACs with status "Covered" vs total ACs
-2. Count adversarial probes executed vs minimum required (1)
-3. If coverage < 80% or probes < 1: VERDICT cannot be PASS
-
-## Sensor 5 — Context budget report
-
-At session end, before writing project-pulse.md:
-1. Estimate how many files were read during the session
-2. If > 8 large files: flag context budget concern
-3. Write to project-pulse.md: "Last session context: {N} files read, estimated {light|moderate|heavy}"
-
-## How sensors differ from gates
-
-| | Gates (guides) | Sensors (feedback) |
-|---|---|---|
-| When | Before action | After action |
-| Blocking | Yes (MEDIUM) | No — advisory |
-| Who triggers | Agent checks before proceeding | Agent checks after completing |
-| Response | Stop + ask user | Log + warn + continue |
-| Example | Gate A before @architect | Rule compliance after commit |
-
-## Progressive adoption
-
-1. **Phase 1 (current):** All sensors are agent-internal instructions. No CLI hooks.
-2. **Phase 2 (future):** Move high-value sensors to `hooks-emit.js` for automated execution.
-3. **Phase 3 (future):** Add configurable sensor severity (warn vs block) in project config.
-
-Sensors should be lightweight — a sensor that takes longer than the action it monitors is worse than no sensor.
+# Harness Sensors — Post-Action Verification
+
+> Load this when you need to verify that agent actions comply with project constraints.
+> Sensors run AFTER the action, not before (that's what guides/gates do).
+
+## When to run sensors
+
+| Trigger | Sensor | Agent |
+|---------|--------|-------|
+| After commit | Rule compliance check | @dev, @deyvin |
+| After spec update | Drift detection vs requirements | @dev, @analyst |
+| After architecture.md written | Constitution compliance | @architect |
+| After feature closure | AC coverage verification | @qa |
+| After session end | Context budget report | All agents |
+
+## Sensor 1 — Rule compliance check
+
+After every commit, verify:
+1. Read all `.md` files in `.aioson/rules/`
+2. For each rule, check if the committed files violate any stated convention
+3. If violation found: do not revert — log warning and continue
+4. Write violations to `project-pulse.md` under "Blockers" if severity is high
+
+**Implementation:** This sensor is agent-internal (instruction-based), not a CLI hook.
+The agent instruction says: "after committing, re-read the rules and verify your commit complies."
+
+## Sensor 2 — Spec drift check
+
+After updating `spec-{slug}.md`:
+1. Compare `requirements-{slug}.md` AC list with `spec-{slug}.md` "Edge cases handled" section
+2. If ACs exist in requirements that are not mentioned in spec: flag as potential drift
+3. Write flagged items to `pending_review` in spec frontmatter
+
+## Sensor 3 — Constitution compliance (architecture)
+
+After writing `architecture.md`:
+1. Read `constitution.md`
+2. For each article, verify:
+   - Article I: Is there a spec artifact that preceded this architecture?
+   - Article II: Is the architecture depth proportional to classification?
+   - Article VI: Does the architecture introduce unnecessary layers?
+3. Self-report: add `## Constitution check` section at end of `architecture.md`
+
+## Sensor 4 — AC coverage verification
+
+After @qa writes its report:
+1. Count ACs with status "Covered" vs total ACs
+2. Count adversarial probes executed vs minimum required (1)
+3. If coverage < 80% or probes < 1: VERDICT cannot be PASS
+
+## Sensor 5 — Context budget report
+
+At session end, before writing project-pulse.md:
+1. Estimate how many files were read during the session
+2. If > 8 large files: flag context budget concern
+3. Write to project-pulse.md: "Last session context: {N} files read, estimated {light|moderate|heavy}"
+
+## How sensors differ from gates
+
+| | Gates (guides) | Sensors (feedback) |
+|---|---|---|
+| When | Before action | After action |
+| Blocking | Yes (MEDIUM) | No — advisory |
+| Who triggers | Agent checks before proceeding | Agent checks after completing |
+| Response | Stop + ask user | Log + warn + continue |
+| Example | Gate A before @architect | Rule compliance after commit |
+
+## Progressive adoption
+
+1. **Phase 1 (current):** All sensors are agent-internal instructions. No CLI hooks.
+2. **Phase 2 (future):** Move high-value sensors to `hooks-emit.js` for automated execution.
+3. **Phase 3 (future):** Add configurable sensor severity (warn vs block) in project config.
+
+Sensors should be lightweight — a sensor that takes longer than the action it monitors is worse than no sensor.