pullfrog 0.1.6 → 0.1.7

package/dist/utils/learnings.d.ts

@@ -4,23 +4,34 @@
  * back into future runs as durable context. Modeled on the PR-summary tmpfile
  * pattern (see action/utils/prSummary.ts):
  *
- *   1. server seeds `pullfrog-learnings.md` from `Repo.learnings` (or empty
- *      when the repo has none yet)
- *   2. the agent reads the file at startup as part of its context, and may
- *      edit it in place at end-of-run when prompted by the reflection turn
- *   3. main.ts reads the file back at end-of-run and PATCHes
- *      `/api/repo/[owner]/[repo]/learnings` if it changed (byte-trim equality
- *      against the seed determines change detection)
+ *   1. server seeds `pullfrog-learnings.md` with the verbatim body of
+ *      `Repo.learnings` (or empty for fresh repos), and parses headings
+ *      server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
+ *      into the LEARNINGS prompt section, not into the file
+ *   2. the agent reads the TOC in the prompt and uses listed line ranges
+ *      to read just the sections relevant to the current task — file can
+ *      grow large, but only targeted ranges hit the agent's context
+ *   3. agent edits the file in place at end-of-run during the reflection
+ *      turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
+ *   4. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if the body changed
  *
  * Edit-in-place avoids stuffing the entire learnings list into both the
  * prompt context and an `update_learnings` MCP tool call (which previously
  * required passing the FULL merged list as a string parameter — an
  * output-token tax that grew linearly with the learnings size).
+ *
+ * Section structure is agent-curated. The reflection prompt teaches
+ * hierarchy + a soft 300-line-per-section cap to keep TOC ranges
+ * agent-targetable on long-lived repos; there is no fixed taxonomy.
  */
 export declare const LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
 export declare function learningsFilePath(tmpdir: string): string;
-/** seed the learnings file with the repo's current learnings, or an empty
- * file when the repo has none yet. returns the absolute path. */
+/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
+ * string for fresh repos). returns the absolute path. the parsed TOC is
+ * carried separately via `RepoSettings.learningsHeadings` and rendered
+ * into the prompt by `resolveInstructions`, so the file on disk is just
+ * the body — no markers, no scaffold, no in-file TOC. */
 export declare function seedLearningsFile(params: {
     tmpdir: string;
     current: string | null;

package/dist/utils/runContext.d.ts

@@ -6,6 +6,21 @@ export interface Mode {
     description: string;
     prompt: string;
 }
+/**
+ * server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
+ * line numbers are 1-indexed against the raw body. computed by
+ * `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
+ * shipped over the run-context JSON boundary; the canonical declaration
+ * lives there. duplicated here because the action runtime can't reach
+ * across into the proprietary root-level codebase, and the JSON wire
+ * means typecheck can't enforce shape equality across both sides.
+ */
+export interface LearningsHeading {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    title: string;
+    startLine: number;
+    endLine: number;
+}
 export interface RepoSettings {
     model: string | null;
     modes: Mode[];
@@ -18,6 +33,7 @@ export interface RepoSettings {
     prApproveEnabled: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;
+    learningsHeadings: LearningsHeading[];
     envAllowlist: string | null;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",