@tduyng/pi-harness-loop 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,381 @@
-# Temporary Holding Version
+# @tduyng/pi-harness-loop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads what the sessions actually did, then proposes the harness part that would change it, and
+keeps the lesson that transfers.
+
+## What it adds
+
+The loop runs when the session goes idle. The extension reads the sessions of the project, and
+if a failure recurred across them, it writes a brief with the evidence, one model call turns
+that brief into the part, and the part is installed. Nothing has to be typed, and the loop
+never takes the session over.
+
+A part that does not lower the rate it was written for is taken back out by the next idle, so
+the always-on context does not keep a rule the sessions did not need. `PI_HARNESS_LOOP=off`
+stops all of it.
+
+`/harness-loop` reports the setup, `/harness-loop propose [id]` runs a proposal now, and
+`/harness-loop lint` reports only the problems. `/harness-loop clear` takes the report off the
+screen, and the next prompt does it as well, so a report read once does not sit above the editor
+for the rest of the session.
+
+The harness tree: the skills and agent profiles pi loads, the problems in them, and what the
+skill block costs on every request. The rules come from pi's own loader, so they do not drift
+from it:
+
+- a skill with no description is dropped at load, so it never reaches the model
+- a skill whose frontmatter name differs from its directory is advertised under the frontmatter
+  name, and a prompt that names the folder does not name the skill
+- a profile with no description is listed as "no description", so the model cannot choose it
+- a skill that tells the agent to run `scripts/something.py` without shipping that file sends the
+  agent after a file that is not there
+
+The findings: what recurred in this session's transcript. The same failure three times, the same
+command three times, the same file read three times, a run that hit a failure and changed
+nothing, a tool call with no result.
+
+The recurrences: what recurred across the sessions of this project. The same failure in two
+sessions, the same command in three, the same file read in five. A defect that shows up in one
+run is noise. A defect that shows up in every run is a property of the harness, and the session
+files already on disk are the runs. A signature that reduces to `<path>` or a bare `Script
+failed` is not a finding, because it names nothing a part can change.
+
+A failure also needs independent evidence. When every session that hit it edited a file and each
+pair of those sessions shares one, they are one piece of work, and a rule written from it would
+encode that task rather than the harness. The recurrence is listed and held back. A session that
+edited nothing met the failure outside the edit loop, so it counts as independent.
+
+The skills nobody opened: pi advertises every skill by name and description in the system prompt,
+so a skill that was never opened is a tax on every request of every session. The report lists
+the advertised ones with the number of characters they cost, and it says how many skills are not
+advertised at all, because a skill the model cannot open cannot be opened by accident.
+
+The lessons: the ones whose cue matches the request in the editor, read from
+`.pi/harness/lessons.jsonl`.
+
+## The loop on its own
+
+The session goes idle, and the loop looks at what the sessions of this project did. The scan is
+cached in `.pi/harness/scan.json` with a fingerprint of the session files, so a session that
+changed nothing does not pay for the scan again.
+
+The parsed form of each session file is cached beside it in `.pi/harness/corpus-cache.json`. A
+scan reads the files that changed, and the rest come back from the cache. At most 8 MB of new
+session files are parsed per idle, and every parsed session is kept. The report says how many
+it sees of the sessions on disk. The session being written is left out, so the file the loop is
+in does not force a rescan.
+
+The cache holds 400 sessions, so the oldest leave only when that ceiling is reached, not when
+the newest few exceed a byte budget.
+
+A failure that shows up in two sessions or more is a property of the harness, and the loop acts
+on it. A command or a file that shows up in every session is a habit, and a habit is a
+judgement call the operator makes, so the loop leaves those to `/harness-loop propose`.
+
+A new error string that is a smaller variant of an edit matching failure the loop already tried
+is not a new finding. The edit tool has one matching mechanic, so the 2-session "oldText must be
+unique" is the 9-session "oldText must match" with a different error string, and a second
+proposal for it is the same rule said twice.
+
+The failure's own command is replayed before a proposal. When it passes, the failure no longer
+reproduces, and the loop writes nothing. The same command runs again after an install, and its
+result stays with the install.
+
+A failure whose message the tree no longer carries is not a property of the harness any more.
+Before it proposes, the loop cuts the ids, the paths and the numbers out of the message, and
+searches the tree for what is left, then the dependencies. When neither has it and git shows a
+commit that touched that text after the last session that hit it, the producer was removed and
+the finding is skipped. The verdict is cached in `.pi/harness/producers.json`, keyed by the
+commit and the last session, because it is a search of the tree.
+
+The loop stands out of the way when the session has something else driving it. A goal that is
+active and the day's budget of five proposals each stop it. The writer is one completion, not a
+turn: it carries the brief, it has no tools, and it returns the files of the part as text. The
+files are parsed, checked and installed by the loop, so nothing the writer says is executed. The
+session is notified with what landed, and it keeps its own turn.
+
+The lesson tool arms itself for the run whose request names a trigger of a lesson that is still
+in force, and it is off otherwise, so the request with nothing to do with a lesson pays
+nothing. The cost on the runs that do arm it is about 259 tokens: the schema, the snippet and
+the guidelines.
+
+## The proposal
+
+`/harness-loop propose [id]` runs the same path for one finding, one recurrence or one skill:
+brief, part, install. The brief asks for a skill, an agent profile or a rule, and the writer
+puts the files in `.pi/harness/<id>/`. The part is read back, checked against the same rules the
+tree is checked against, and installed. A part that breaks a rule is not installed, and the rule
+it broke is recorded with it. A reply with no file block leaves `REPLY.txt` beside the brief,
+which is what the writer said instead.
+
+A part under `global/` holds in every project. A skill under `global/` goes to the skills every
+project loads, and a global rule goes to the context file every project reads. It is not
+installed unless `global` is set in `.pi/harness.json`, because one project's failure does not
+get to become every project's rule. Without it the part lands in the project: `.agents/skills/<name>/`,
+`.pi/agents/<name>.md`, and the project's context file for a rule.
+
+The prompt says what each form costs. A skill is paid for by its name and description, about 300
+characters on every request, and its body costs nothing until the model opens it. A rule is paid
+for by its length and always applies. The rule wins when the behaviour has to hold every time,
+and the skill wins when the situation is specific enough to route on.
+
+The part may also carry `CONFIRM.md`, one shell command that exits 0 only when the finding can
+no longer happen. It must not write files or use the network. The loop runs it after the project
+check, and a confirmation that fails puts the part back. The brief asks for the command, and a
+part without one installs on the project check alone, recorded as unconfirmed.
+
+When the part passes, the session records the lesson that transfers: the cue (the shape of
+situation), the lesson (the operation on the harness), the way to confirm it worked, the
+evidence it rests on, and a confidence. The model may decline with `NO_ENTRY`, and then nothing
+is written. A block with no confirm line is dropped, because a rule nobody can check is a rule
+of thumb. The lesson is appended to `.pi/harness/lessons.jsonl` and matched against later
+requests by its trigger words. A lesson about a situation an earlier lesson already covers
+replaces it: the old one keeps its record, stops matching, and the report names the install
+that still holds the old rule.
+
+The trigger words are the ones the prompts of this project actually used, because a word no
+request ever carried cannot route to anything. A trigger seen once has to be at least eight
+characters and pass a consonant check. A typo is the rarest token in the corpus, and it routes
+nowhere.
+
+A request matches when it carries two triggers, or one trigger of six characters or more that
+the project rarely uses: one short word is a coincidence, and `key` is in half the requests of a
+project that does not talk about credentials. Two processes that record the same cue leave two
+lines in the file, and the read keeps the newest active one, so the same situation does not arm
+twice. A match records a use, so a lesson nobody ever recalls is visible in the record.
+
+## The lint
+
+`/harness-loop lint` is the harness check on its own: the skills and agent profiles pi loads,
+against the rules pi's own loader applies, and the extension layer on top.
+
+The skill rules are the ones that bite silently. A skill with no `description` is dropped at
+load and never reaches the model. One whose frontmatter name does not match its directory is
+advertised under one name and looked for under another. Another that calls a helper script it
+does not ship points at a file that is not there. Two skills with the same name means the second
+one is dropped. An agent profile with no `description` is listed as "no description".
+
+The extension rules are the ones the repo's own scripts do not cover. A package under
+`extensions/` that declares an entry the root manifest never loads is a package nobody gets.
+An entry file that is not on disk is a manifest that points at nothing.
+
+The rule rules matter because the project's check cannot fail for a rule. A rule is markdown in
+a file no test reads, so the lint is the only gate it passes. A rule without a heading cannot
+be replaced later, a rule longer than thirty lines pays for itself on every request of every
+project, and a rule that carries a credential lands in a file every session reads.
+
+## The check decides
+
+A part that passes the rules can still be wrong, and pi has no grader to say so. So the part is
+installed and the project's own check runs against it. A rule part installs without a check,
+because no test reads a markdown file, and the rate verdict below is what holds it. A skill or a
+profile waits for the check. The check is the first of:
+
+- `check` in `.pi/harness.json`
+- the `test` script in `package.json`, run with `bun run test` or `npm test`
+- the `test` recipe in `justfile`
+
+The check runs before the change and after it. The part is installed first, so the common case
+costs one run of the suite: when the check passes, the part stays. When it fails, the part goes
+back the way it was and the check runs once more on the tree without it, so the verdict is about
+the difference. A suite that was already failing the same way is not read as a verdict against
+the change. A part that adds a failure is put back, and no lesson is recorded, because a part the check turned
+down taught nothing.
+
+When the part carries a `CONFIRM.md` command, that command runs after the project check. A
+confirmation that fails puts the part back, because the part did not prove the finding gone. The
+command and its output stay with the install.
+
+When the finding carried a command, it is replayed after the install. Its result is recorded but
+does not decide the install, because the project check and the confirm command are the gates.
+Three installs a day is the ceiling for the loop, and the operator's own hand is not counted
+against it. The count is in `.pi/harness/installs.jsonl`. The ceiling is a budget that frees
+after a day, not a verdict: a proposal that lost to the budget stays open and the loop tries it
+again, and the spend is counted once.
+
+A second ceiling is the prompt itself. `maxStandingTokens`, 1,500 by default, is how many tokens
+the active installs may add together to the front of every request. An install that would cross
+it stays on disk with its brief, and the message names the current total, so the way through is
+to revert a part that did not carry rather than to raise the cap. A rule is paid in full on every
+request, which is why this ceiling counts the rule text and only the name and description of a
+skill. The report prints the standing total in tokens. `0` turns the ceiling off.
+
+A rule is identified by its heading, so a rule that is revised replaces the rule it revises
+rather than saying it twice.
+
+## The sessions decide whether it held
+
+The check says the part did not break the project. It cannot say the failure stopped, and for a
+rule or a skill it cannot see the part at all, because no test reads a markdown file. So the
+install is read against the sessions that come after it.
+
+The signature of the finding is counted per session, before the install and after it. The rate
+is failures per session, and every session counts whether it hit the failure or not, because a
+session that did not fail is the evidence. The verdict:
+
+- `held` when the rate fell to three quarters of what it was, including to zero, and the
+  sessions after it still call tools at more than half their old rate
+- `flat` when it stayed within a quarter either way
+- `worse` when it rose by a quarter or more
+- `avoided` when the rate fell but the work did too, so the failure stopped because the agent
+  did less rather than because the part reached it
+- `confounded` when a commit touched the failure in the window, so the rate is not the part's
+- `early` until three sessions have run after the install
+- `out-of-window` when the corpus no longer holds a session from before it
+
+The work rate is the calls of every tool per session, read from the same parse as the
+signature, and a cache written before it counted tool calls reads as unknown and skips the
+check. The count is across tools rather than per tool, because a session that switched from
+`edit` to `write` did the work and fixed the failure.
+
+The verdict is computed on idle as well as in the report, so a lesson whose part did not carry
+stops matching without anyone typing a command.
+
+A `flat`, `worse` or `avoided` install is not the end of the finding. The loop tries it again,
+the brief says the earlier form did not carry and shows the two rates and the form itself, and
+the lesson that came with it stops matching, because a rule nobody can act on is worse than no
+rule. A finding whose part was all markdown and still did not carry is marked `needs code`. The
+loop stops proposing prose for it, because the failure lives in tool behavior and a rule cannot
+reach it. The report shows the verdicts, and a `held` finding is the one thing the loop can call
+done.
+
+A finding comes back as soon as the failure grows past the count it had at the last proposal,
+and a finding stops after three proposals, so one failure cannot spend the week's budget
+rephrasing the same rule.
+
+`/harness-loop revert <install>` puts the files back by hand, and the newest install goes first
+when two of them touched the same file. A file whose content changed after the install is left
+alone and named, because the operator's edit is not the loop's to overwrite. `/harness-loop
+install <id>` runs the same path over a part that is already on disk. One install runs at a time,
+through a lock beside the record.
+
+`.pi/harness.json` turns the loop off or changes the ceiling:
+
+```json
+{
+  "check": "bun run test",
+  "auto": false,
+  "autoInstall": false,
+  "global": false,
+  "maxInstallsPerDay": 3,
+  "maxStandingTokens": 1500,
+  "writerModel": "opencode-go/mimo-v2.6-flash"
+}
+```
+
+`writerModel` is the model that writes the part. The loop reads three answers in this order:
+`writerModel` in the project's `.pi/harness.json`, `PI_HARNESS_WRITER_MODEL` in the environment,
+then the `model` in `.pi/subagent.json` or `~/.pi/agent/subagent.json`, which is the model pi
+already runs chores on. With none of them it uses the model of the session that is running, and
+a session on an expensive model pays that model for a short chore. The writer sees the brief
+and nothing else, so another model loses no context by writing it.
+
+`auto` is read when the session goes idle, and it stops the loop from writing a part on its
+own. The manual command still works. `autoInstall` is read when the part is ready, so a project
+that wants every change by hand sets it to `false` and the part stays on disk.
+`PI_HARNESS_LOOP=off` in the environment turns the automatic run off for every project without
+changing a file, and the command still works.
+
+A rule part installs without a project check, because no test reads a markdown file. A skill or
+an agent profile needs the check, because it changes what the loader sees. What a rule is held
+to instead is the rate of the failure it was written for: flat, worse or avoided after three
+sessions and the loop reverts it, records `auto-reverted`, and stops proposing prose for that
+finding.
+
+## Taking it back out
+
+The loop reverts its own part when the sessions after it show the same rate or a worse one. The
+files go back byte for byte, the install is recorded as reverted with the two rates, and the
+finding is marked needs code, so the next attempt has to live in the tool rather than in a rule.
+A file the operator changed after the install is left alone and named, because that edit is not
+the loop's to overwrite.
+
+## What the loop spends
+
+The loop is not free. A proposal costs one completion, and the completion carries the brief
+with the evidence, which is the whole input. `writerModel` names the model that runs it, and
+the output is the part. The tokens the provider reported are written to
+`.pi/harness/spend.jsonl` with the outcome, so a budget of five proposals a day is five
+completions and not five sessions. The report sums them.
+
+A part also costs the prompt after it is installed, and that cost is not a completion. Every
+install records the characters it adds to the front of the prompt, which is the rule as it is
+appended or the name and description a skill is routed on, and the report sums the active ones.
+The brief carries that sum, so the writer knows what this project already pays on every request
+before it chooses a rule over a skill.
+
+## What it works with
+
+The other extensions drive the same session, so the loop reads their state instead of guessing at it.
+
+`pi-goal` owns the turns of a session with a goal. The loop does not propose while a goal is
+active, and it waits to install while one is, because both of them would be driving the same
+session at the same time.
+
+`pi-goal` owns the check runner in `src/check.ts`. The loop uses the same runner, so
+the two do not disagree about what a check said.
+
+`pi-context` prunes the context the model sees, not the session, so the findings still see the
+whole branch. The recurrences read the session files, which no compaction touches.
+
+`pi-guard` blocks the shell from reading credentials. The rule it needs is in the global
+context, and it says what to do instead of what is blocked.
+
+## What it found here
+
+The measurements come from the sessions on this machine, so they are about this setup rather than
+about pi.
+
+- 12 of the 19 skills are not advertised at all, because their frontmatter says
+  `disable-model-invocation`, so they cost nothing. The other 7 are advertised, and the block
+  they make is 2,652 characters, about 663 tokens on every request of every project.
+
+- 5 of those 7 were opened in none of the 26 sessions scanned last. They cost 1,447 of the 2,652
+  characters, about 362 tokens per request. `tdd` was the sixth, and the loop's finding for it
+  is the one change that came from a proposal and nothing else: 39 sessions, no open, and the
+  skill stopped being advertised on 2026-10-26.
+
+  An open is a read of a `SKILL.md` or a `/skill:<name>` command in a prompt, so a skill reached
+  by hand is not called dead. The report names the rest and the number, and the operator
+  decides, because a skill that was never needed is not the same as a skill that cannot be
+  found.
+
+- The shell blocked 14 reads of credential files across 2 sessions, and every retry with another
+  shell reached the same block.
+
+  The rule that came out of it is in the global context, and it says what to do instead of what
+  is blocked.
+
+- The edit tool rejected 9 old texts across 4 sessions, and each rejection reported a closest
+  match the model had paraphrased.
+
+  The rule that came out of it says to copy the old text out of the output of the read that
+  preceded the edit, and to read the file again when an edit is rejected.
+
+- 4 reads were refused for being over 350 lines across 3 sessions, and each one was a file a
+  grep would have narrowed.
+
+  The rule that came out of it says to grep first.
+
+## Why the report is a command and not a tool
+
+A tool would put its schema in the system prompt of every session, which is the tax this package
+exists to reduce. The command costs nothing until it is typed.
+
+The lesson tool is the one tool, and it arms itself for the run whose request names a trigger
+of a lesson in force, so a session can record a lesson the moment it hits the failure that
+taught it. It is 259 tokens on the runs that arm it and nothing on the others. The words that
+count are the ones that say the situation: a word in more than a fiftieth of the prompts is
+noise, and a word no prompt ever used cannot route. The tool is fixed for the run, so a failure
+that surfaces in a later turn of the same run still finds it.
+
+## What it is not
+
+It does not score the harness. It measures the rate of the failure a part was written for,
+which is not the same as the work being better: a session ends, and nothing says whether the
+work was good. The findings are the part that can be read without a grader, and the rate is the
+part that says whether the part held.
+
+It does not compare two runs of the same task. The comparison it makes is across the sessions
+of this project, which are different tasks. The same task run twice is what a benchmark does,
+and what a working session does not.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@tduyng/pi-harness-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Reads what the session repeated, proposes the harness part that would have prevented it, and records the lesson that transfers.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "harness",
+    "reflection"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-harness-loop#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-harness-loop"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}