<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Yioop — Development process for LLM co-implementers</title>
<style>
body { font-family: system-ui, sans-serif; max-width: 760px;
margin: 2rem auto; padding: 0 1rem; line-height: 1.5;
color: #1a1a1a; }
h2 { margin-top: 2rem; border-bottom: 1px solid #ddd;
padding-bottom: 0.2rem; }
h3 { margin-top: 1.4rem; }
ol, ul { margin: 0.4rem 0; }
li { margin: 0.35rem 0; }
.note { color: #555; font-size: 0.92em; margin: 0.6rem 0 1.2rem; }
.counter { background: #fff4e5; border: 1px solid #f0c890;
border-radius: 6px; padding: 0.6rem 0.9rem; margin: 1rem 0; }
code { background: #f2f2f2; padding: 0 0.2em; border-radius: 3px; }
</style>
</head>
<body>
<h1>Yioop — Development process for LLM co-implementers</h1>
<p class="note">How Chris Pollett likes development to run, written for an
LLM working with him on Yioop. Most of this is shared with his other
projects; what is specific to Yioop — the gold/work sync, the
Createdb check, the locale and library rules — is marked. When
something says "always" or "never," treat it as a hard rule.</p>
<div class="counter">
<b>Round counter.</b> Keep a count of rounds since you last re-read this
file. A round is one exchange: Chris says something, you respond. Echo the
current count in every response so it is visible. When the count reaches
10, re-read this whole file before writing your next response, then reset
the count to 0 and tell Chris you re-read it. This is a memory aid: it
keeps these conventions fresh over a long session instead of letting them
drift. The same counter runs in atto's copy of this file.
</div>
<h2>How changes move (Yioop-specific): gold and work</h2>
<p>Yioop is developed against a two-clone discipline, not a shared remote
you push to:</p>
<ul>
<li><b>gold</b> is the confirmed line of history. It is fast-forwarded
only when Chris has confirmed a commit, and its
<code>confirmed-head</code> tag marks that point. Your local gold
hashes are your own and will not match Chris's hashes.</li>
<li><b>work</b> is a throwaway clone of gold where changes are made. It
is re-cloned from gold after every gold fast-forward, with the
configured <code>work_directory</code> restored into it.</li>
</ul>
<p><b>gold is a vault, not a workbench.</b> Exactly two operations ever
touch gold: cloning it to make work, and fast-forwarding it with
<code>git apply</code> of a patch Chris has confirmed. Nothing else, ever.
Never run a build, a test, a golden regeneration, a <code>Createdb</code>,
a <code>ConfigureTool</code>, or any other command inside gold; never
create a <code>work_directory</code> there; never hand-edit, hand-copy, or
hand-commit a file into it. Every build, test, and regeneration happens in
a work clone, and a regenerated golden reaches gold only inside a patch.
Reconciling a divergence is no exception: rebuild the wanted state in work,
cut a patch, and apply that to gold. If you ever find yourself about to go
into gold to run something — even just to check a result or to get
back in sync — that urge is the process breaking; stop, and do it in
work.</p>
<p>The loop each round, and this must be done <b>prior to any new
work</b>: the moment Chris confirms a patch by pasting its hash, and
before writing or changing a single line for the next task, apply Chris's
latest confirmed patch to gold, commit it, move the
<code>confirmed-head</code> tag, re-clone work, and restore
<code>work_directory</code>. Starting new work on a gold that has not been
synced is the most common way the two lines drift: the next cut is taken
against a stale <code>confirmed-head</code> and silently double-includes
the patch Chris already confirmed. If you notice that a round's work has
already begun on an unsynced gold, do not re-clone work — that would
discard the in-progress changes. Instead advance gold to the confirmed
commit, move <code>confirmed-head</code> to that commit in both gold and
work, and only then cut. Cut a delivery as <code>git diff
confirmed-head..HEAD</code>, and dry-run it with <code>git apply
--check</code> on a fresh clone checked out at <code>confirmed-head</code>
before presenting. Apply patches forward only — never reverse-diff.
Never assume anything is committed until Chris reports the hash. Name a
patch for what it does in plain terms, never a sequence number or a
plan-item number.</p>
<h2>Setting up the dev environment (Yioop-specific)</h2>
<p>Beyond the gold/work clones above, a work clone needs a configured
<code>work_directory</code> before it will build or run. Restore the
configured <code>work_directory</code> into the fresh work clone, point Yioop
at it with <code>php8.3 src/configs/ConfigureTool.php work-dir</code>, then
build the two SQLite databases with
<code>php8.3 src/configs/Createdb.php</code>, which should print
“Create DB succeeded.” Without a configured
<code>work_directory</code>, <code>Config.php</code> stops short of defining
its later constants (for example <code>MAX_GROUP_PAGE_LEN</code>) and Createdb
dies with an undefined-constant error — that failure is the
environment, not your patch. Createdb also regenerates
<code>work_directory/app/locale</code>; since <code>LOCALE_DIR</code> prefers
that copy, delete it after Createdb so translations fall back to the current
<code>src/locale</code> when you render a page.</p>
<h3>Tools that ship with Yioop</h3>
<ul>
<li><code>src/executables/CodeTool.php</code> is the general-purpose tool.
Run a test script with <code>php src/executables/CodeTool.php unit
<TestFile></code> (or <code>unit list</code> /
<code>unit ClassName methodName</code> to target cases); check docblocks
with <code>needsdocs <file></code>; and check the 80-column rule with
<code>longlines <file></code> (multibyte-aware, so it is the
authority over a raw byte count).</li>
<li>There are many Command-line tools that can easily be installed in this
environment:
<code>lynx</code> and <code>curl</code> for fetching and reading pages as
text, plus <code>node</code> and <code>npm</code>. Rather than say don't
have the tool you want, try to install it.</li>
</ul>
<h3>Getting a headless browser</h3>
<p>You have used a headless renderer here before:
<code>wkhtmltoimage</code> and <code>wkhtmltopdf</code> are installed and turn a
page or an HTML fragment into a PNG or PDF with no X server. They are built on
WebKit, which descends from Konqueror's KHTML, so they draw a page much as a
browser would — enough to eyeball a layout or confirm a fragment
renders. The bundled <code>/usr/bin/chromium-browser</code>, by contrast, is a
snap wrapper that cannot launch here and errors that it “requires the
chromium snap.” For scripted measurement of computed styles (reading
<code>getBoundingClientRect</code>), a scriptable browser is needed: install a
Chrome-for-Testing build with <code>npx @puppeteer/browsers install
chrome</code> and drive it from <code>puppeteer-core</code> with
<code>--no-sandbox</code> and <code>--disable-dev-shm-usage</code> (not
<code>--single-process</code>, which breaks the DevTools pipe); its download
host is not in the default network allowlist, so add it to the sandbox network
settings first. When no scriptable browser is set up, render to an image with
<code>wkhtmltoimage</code>, reason about the cascade, and ask Chris to confirm
the pixels.</p>
<h2>Presenting Options</h2>
<ul>
<li>Avoid fixed list choices as Chris views these with suspicion like
you are deliberately trying to limit his options.</li>
<li>If you still have a choice of things you are presenting to Chris, you
should always present them as plain text, never present a choice
gadget of any kind.</li>
</ul>
<h2>Coding conventions (shared across projects)</h2>
<ul>
<li><b>80 columns.</b> No line over 80 characters. When a patch touches a
file, fix every pre-existing long line in it too (autogenerated files,
such as <code>src/configs/PublicHelpPages.php</code>, are the
exception).</li>
<li><b>Braces always</b> on every <code>if</code>, <code>else</code>,
and loop body.</li>
<li><b>Block comments only</b> (<code>/* ... */</code>); never
<code>//</code>.</li>
<li><b>No dead code.</b> If a change makes nearby code a no-op or
pointless, delete it and say so.</li>
<li><b>No magic numbers.</b> Every literal — size, limit, timeout,
conversion factor — gets a named constant with a docblock; grep
<code>Config.php</code> for an existing one to reuse first.</li>
<li><b>No single-letter variables</b> except loop indices <code>i</code>,
<code>j</code>, <code>k</code>, in both PHP and JavaScript.</li>
<li><b>No type or unit suffixes on names</b> (<code>_arr</code>,
<code>_str</code>, <code>_int</code>, <code>_obj</code>,
<code>_bool</code>, <code>_list</code>, <code>_secs</code>,
<code>_ms</code>, <code>_bytes</code>, ...). Put the unit in the
docblock: <code>HEARTBEAT_POLL</code>, not
<code>HEARTBEAT_POLL_SECS</code>. (<code>_info</code>, <code>_max</code>,
<code>_name</code> read as words and are fine.)</li>
<li><b>Docblocks everywhere.</b> Every class and method has a docblock
whose first sentence a layperson can read: what it does and why. RFC or
encoding specifics come after, in plain terms; a citation standing in
for an explanation counts as undelivered code.</li>
</ul>
<h2>Yioop-specific rules</h2>
<ul>
<li><b>Locale keys are string literals.</b> Never put a variable or a
ternary inside <code>tl()</code>; extract the key to a variable first.
The locale extractor only matches <code>tl('literal_key')</code>.</li>
<li><b>Library classes are pure logic.</b> Nothing in
<code>src/library/</code> may touch a model or the database, call
<code>tl()</code>, or escape/sanitize. Components, controllers, and
helpers may. The atto servers (<code>WebSite.php</code>,
<code>MailSite.php</code>) go further: no <code>L\</code> or
<code>C\</code> references and no <code>Config</code> reads at all, so
keep any conversion constants local to the file, named
<code>X_PER_Y</code> with units in the docblock. Know decimal versus
binary: <code>metricToInt</code> is decimal (powers of 1000) and does
not match PHP's binary <code>memory_limit</code> "M" (1024×1024).</li>
<li><b>Schema changes update the Createdb seeds.</b> Any column add or
remove needs the matching explicit column-list INSERTs in
<code>src/configs/Createdb.php</code>; positional seeds break on a
fresh install.</li>
<li><b>Once a schema version is gold, never change it in place.</b> If a
patch that bumped <code>DATABASE_VERSION</code> and added a migration has
been confirmed gold, do not edit that version's tables, migration, or
<code>Createdb</code> seeds to make a further schema change. Bump
<code>DATABASE_VERSION</code> again and write a new migration, so a
database already upgraded to the confirmed version can move forward. A
confirmed version's database exists in the wild (at least on Chris's
machine); its version already matches, so an in-place edit never re-runs
and strands that database. Put differently: whenever something that
involved a DB change is called gold, the next schema change gets its own
version bump and migration. When unsure whether a change touches an
already-gold schema, add a new version.</li>
<li><b>The database stores raw functional values.</b> Do not store
<code>htmlspecialchars</code>-escaped text; that breaks functional use
and double-escapes at display. Controllers escape for the view at
render time.</li>
<li><b>SQL stays portable</b> across SQLite, MySQL, Postgres, Oracle, and
DB2. Avoid backend-specific syntax; <code>VARCHAR</code> widths matter
off SQLite. There are two SQLite databases, <code>public_default.db</code>
and <code>private_default.db</code> — never say just
"default.db."</li>
<li><b><code>PublicHelpPages.php</code> is autogenerated</b> —
never patch it directly. Deliver wiki help source as a
<code>.txt</code> file for Chris to paste through the wiki UI.</li>
</ul>
<h2>Tests</h2>
<p>As code is developed, unit tests should be created. Unit tests live
in <code>tests/</code>; a case is a method named
<code><name>TestCase()</code> (not <code>test<Name></code>) and
asserts with <code>assertEqual</code>, <code>assertTrue</code>, and the
like. Run one with <code>php src/executables/CodeTool.php unit
<TestFile></code>, and list or target cases with <code>unit
list</code> / <code>unit ClassName methodName</code>. Pull pure logic out
so it can be checked on its own. Flag any test over about
0.01 seconds — it usually means unintended I/O. When patching a
locale, edit <code>src/locale/<tag>/configure.ini</code> directly; it
takes effect immediately, no extraction step. Call the data a test stands
up its "test set-up" or "test data," never a "fixture."</p>
<h2>The audit before every patch</h2>
<p>Run these as separate checks and report PASS or FAIL for each. The
CodeTool commands used are noted where they apply.</p>
<ol>
<li><code>php -l</code> on every touched file.</li>
<li><code>CodeTool.php needsdocs <file></code> returns 0 —
every class and method has a docblock.</li>
<li>No new single-letter PHP variables except <code>i/j/k</code>.</li>
<li>No banned identifier suffixes.</li>
<li>No <code>//</code> comments.</li>
<li>No new single-letter JavaScript variables except
<code>i/j/k</code>.</li>
<li><code>CodeTool.php longlines <file></code> clean — no line
over 80 columns in a touched file.</li>
<li>Every <code>if</code> body is braced.</li>
<li>No banned words and no dead code.</li>
<li>A fresh <code>php src/configs/Createdb.php</code> against a configured
SQLite work directory prints "Create DB succeeded" (verify the USERS
column count and the root/public rows).</li>
</ol>
<h2>Verify before you state</h2>
<ul>
<li>Read the actual code before asserting how it behaves. If it is not in
view, say so — never present a guess as a mechanism.</li>
<li>Grep for a named helper before claiming it does not exist. Chris
wrote the codebase; a function he names usually is there.</li>
<li>For anything visual (CSS, JS layout), do not guess at output: render
it headless and measure computed styles against a reference commit.
For server behavior, run it and confirm before presenting.</li>
<li>If a change might make nearby code slower or redundant, say so
plainly rather than hiding it.</li>
</ul>
<h2>Delivering a patch</h2>
<ul>
<li>Prefer one larger, complete, testable patch over a run of tiny ones.
A cohesive feature ships as a single patch; fold a small fix into the
next larger one rather than cutting a patch for it alone.</li>
<li>Present the pass/fail audit, a plain-English sentence or two on what
the patch does, and exactly what to run and look for to check it.</li>
<li>Every code patch also carries its devlog update — the next plan
item checked off with a short how-it-was-done note — committed
inside the same patch.</li>
<li>Do not check off a devlog item until Chris says it is done. When he
does say to check an item, check it in the arc plan <em>and</em> update
the master to-do file <code>devlog/v10/yioop_v10_todo.html</code> at the
same time: mark or adjust the matching phase and backlog-item entry
there (its <code>box</code>/<code>part</code>/checked markers) so the
arc plan and the master list never drift out of sync.</li>
</ul>
<h2>Devlog</h2>
<p>Work is logged under <code>devlog/v10/</code> in dated arc folders named
<code>YYYY-MM-DD Arc Name/</code>, each with an HTML plan document. The
devlog is append-only: a finished item keeps its checkmark and note as a
permanent record, and a later hotfix goes under the current arc's plan as
"other work accomplished," not a new dated folder. The only circumstance
where a new arc should be created is Chris says so
first; until he does, everything, including work that feels like a separate
concern such as a production hotfix, goes under the current arc's plan as
other work. Before presenting, check that the plan's numbering is internally
consistent and that what is marked done lines up with what is next. Try
to follow the rules for traditional outlining call for outlines to begin
with Roman numerals (I, II, III) and to proceed through letters
(A, B, C, and a, b, c) and Arabic numerals (1, 2, 3).</p>
<p>Getting oriented at the start of a session: if you are new to the v10
to-do and its development phases, read the master list
<code>devlog/v10/yioop_v10_todo.html</code> first, then the current arc's
plan. Each finished arc from <code>2026-06-16A Mail Refactor Arc</code>
onward carries a three-to-four sentence “Arc Post-Mortem Summary”
paragraph just under its title that says what the arc accomplished, so you can
catch up quickly without reading every item. When an arc is finished, add such
a summary to its plan so the next co-implementer gets the same head start.</p>
<h2>Words and phrases to avoid at All Costs</h2>
<p>These words and phrasings should be excluded from all of your output
even transient.</p>
<ul>
<li>Avoid at all costs <b>harness</b>; <b>ctor</b> (write "constructor");
<b>rails</b>; <b>sidecar</b> (say ".flags/.date companion files");
<b>fixture</b> (say "test set-up"); <b>nit</b>;
<b>goldens</b> (say "expected-output files");
<b>slug</b> (say "page name" or "url name");</li>
<li></li>
<b>proof</b>/<b>proven</b>/"I proved" only if can give a formal
proof in lean. For empirical results (say "evidence").</li>
<li>Avoid at all costs, lead in phrases that imply dishonesty:
<b>to be honest</b>, <b>honestly</b>, <b>genuinely</b>, <b>plainly</b>
<b>actually</b>, "the honest finding," "straight with you." All of these
imply you are trying to be dishonest usually. It is better to avoid
unnecessary phrases to begin and adhere as close as possible to simple
English</li>
<li>Avoid presuppositional phrasings. For example, "Send me the commit hash
once you've applied and confirmed it, ..." implies that I will find your
code suitable rather give me a chance to evaluate it fairly.
</li>
</ul>
<h2>Acronyms and citations</h2>
<ul>
<li>All acronyms should be spelt out in full the first time it
appears in a round — write "Content-Security-Policy (CSP)", then
"CSP" afterward, not "CSP" cold. A bare initialism costs Chris a decode
step; for instance CSP reads to him first as Constraint Satisfaction
Problem, so lead with the words.</li>
<li>For an RFC (a numbered internet standards document), the first time
you cite one give both the number and, in plain words, what it covers
— "RFC 6265, the HTTP cookie specification", not just
"RFC 6265".</li>
</ul>
<h2>Running things in this environment</h2>
<ul>
<li>Chris's shell is tcsh; write commands and scripts in tcsh syntax (no
bash-style loops; single-quote any string containing <code>!</code>).
</li>
<li>Start an atto or PHP server so it cannot hang the session: give it a
self-terminating timeout that cannot be trapped, e.g. <code>timeout -s
KILL 12 php index.php ... </dev/null >/tmp/log 2>&1
&</code>, and give <code>curl</code> a <code>--max-time</code>.</li>
<li>Free a busy port before a fresh run with <code>fuser -k
8080/tcp</code>; a stale server on the port answers with old code and
hides the change under test.</li>
</ul>
</body>
</html>
(c) 2026 Seekquarry - Open Source Search Engine Software