You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Process: architecture decision records — write the ten decisions the code already embodies (value representation, memory model, TU granularity, extension boundary, JIT tier, PHP baseline, supported extension set, self-host scope, LLVM version, patch strategy) and open the four the maintainer still has to make (docs/adr/) #36402
Foundation: · make direction explicit so 100 agents pull the same way · child of #36379
Why
The repo's direction lives in scattered places: .cursor/rules/*.mdc, docs/roadmap/*.md, docs/architecture-review-2026-07.md, README, tracker issues, and memory notes on the maintainer's box. Agents re-derive it per session and sometimes contradict it (a "fix" that boxed every int; a JIT tier that silently interprets). Each wave-1 root cause maps to an unstated decision. ADRs are the standard, cheap fix: one page per decision, status, context, consequences, superseded-by.
Four DECISION issues for the maintainer, each an ADR draft with options and a recommendation: JIT tier future (keep MCJIT / move to ORC after LLVM 22 / retire phpc serve --jit in favour of AOT + fast VM — recommendation: retire until ORC), PHP baseline (Stdlib: pow, strval, and expanded PHPT specs #6: 8.3), supported extension set for v2.0 (from the 84 dirs: standard, spl, ctype, hash, random, json, mbstring, pcre, date, session, curl, pdo/sqlite, dom/xml, openssl, sodium, zlib; everything else "experimental"), self-host scope (Stdlib: string search builtins and is_array #15).
AGENTS.md links the ADR index; new architectural PRs must reference an ADR or add one.
Done when
Ten ADRs merged; four DECISION issues answered by the maintainer and folded into ADRs
check-generated-docs.sh verifies the ADR index; AGENTS.md links it
Category
Foundation:· make direction explicit so 100 agents pull the same way · child of #36379Why
The repo's direction lives in scattered places:
.cursor/rules/*.mdc,docs/roadmap/*.md,docs/architecture-review-2026-07.md, README, tracker issues, and memory notes on the maintainer's box. Agents re-derive it per session and sometimes contradict it (a "fix" that boxed every int; a JIT tier that silently interprets). Each wave-1 root cause maps to an unstated decision. ADRs are the standard, cheap fix: one page per decision, status, context, consequences, superseded-by.Deliverable
docs/adr/0001-…for the settled decisions: (1) boxed__value__16 B + native fast paths with guards, (2) refcount + cycle GC, request arena for workers,{main}ownership same as functions, (3) per-unit translation units with an ABI manifest, (4) core + ext/standard mandatory, other extensions side-loaded viaext.json, (5) differential-against-Zend as the primary correctness oracle, (6) generated docs only, (7) gen-0 as a release artifact, (8) LLVM 9 now → 22 via pointee threading, (9) vendored forks instead of patches (Foundation: patches/ are no longer the source of truth — apply-patches.sh is 7,508 lines with 85 overlay functions and 412 grep guards, 92 of 183 patches neither apply nor reverse cleanly; fork php-cfg/php-types and keep patches only for php-llvm (patches/, script/apply-patches.sh) #36229), (10) fleet Definition of Done (Stdlib: array_pop, array_shift, array_values, sizeof #22).phpc serve --jitin favour of AOT + fast VM — recommendation: retire until ORC), PHP baseline (Stdlib: pow, strval, and expanded PHPT specs #6: 8.3), supported extension set for v2.0 (from the 84 dirs: standard, spl, ctype, hash, random, json, mbstring, pcre, date, session, curl, pdo/sqlite, dom/xml, openssl, sodium, zlib; everything else "experimental"), self-host scope (Stdlib: string search builtins and is_array #15).AGENTS.mdlinks the ADR index; new architectural PRs must reference an ADR or add one.Done when
check-generated-docs.shverifies the ADR index; AGENTS.md links it