1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
# Agent Instructions
This project uses **bd (beads)** for issue tracking. Run `bd init` once (inside
this directory), then `bd prime` for full workflow context.
## Quick Reference
```bash
bd init # First-time setup (once)
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work atomically
bd close <id> # Complete work
bd create # Create beads per the phase plan (see docs/roadmap.md)
```
## Build & Test
```bash
composer install # once (phpunit is dev-only)
composer check # lint + unit tests — the quality gate
composer test # vendor/bin/phpunit only
composer bench # registration/dispatch scaling benchmark (manual, not CI)
```
## Conventions
- PHP namespaces follow PSR-4 under `BrettParson\MiniRoute\` → `src/`.
- Interfaces end in `Interface` (e.g. `MiddlewareInterface`).
- Attributes live in `src/Attribute/`.
- Keep runtime dependencies at zero; `phpunit` is dev-only. See `README.md`.
- Controllers accept `RequestInterface` and return `ResponseInterface`.
- Known-issue baselines live in `tests/Regression/KnownIssuesTest.php` and
flip to desired behavior when their fix lands — never delete them.
- Every user-facing change gets a line in `CHANGELOG.md` under Unreleased.
## Beads operations
- The embedded Dolt database allows ONE writer at a time: never run two `bd`
commands in parallel (they collide on the lock). Serialize them.
- Never use `bd edit` (opens an editor). Use `bd update --title/--description`.
- `bd prime` restores full workflow context after compaction or a new session.
## Changelog
- Add a line under `[Unreleased]` for every user-facing change.
- Release: rename Unreleased to the version, bump `composer.json`, tag `vN.N.N`,
push, then trigger a Packagist update (webhook or the Update button on the
package page). See `CHANGELOG.md` header for the full convention.
## Non-Interactive Shell Commands
Use `cp -f`, `mv -f`, `rm -f` (and `-rf` for recursive) to avoid hanging on
interactive confirmation prompts.
## Session Completion
When ending a work session, file issues for remaining work, run tests, update
issue status, and push (`git push`, `bd dolt push`).
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
## Beads Issue Tracker
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
### Quick Reference
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
```
### Rules
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
## Session Completion
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
**MANDATORY WORKFLOW:**
1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
```bash
git pull --rebase
bd dolt push
git push
git status # MUST show "up to date with origin"
```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session
**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
<!-- END BEADS INTEGRATION -->
|
