Write learnings/ to a teamai-learnings branch (direct push, no PR) #485

Activity

1. SaulMoro commented on Sep 17, 2026

   

   SaulMoro

   on Sep 17, 2026

   Last edited by SaulMoro

   Collaborator

   More actions

   The name works, and so does the shape. A dedicated regular branch, direct push, and reuse of the worktree, lock, and retry code without sharing REPORTS_BRANCH or the reports worktree. Options 2 and 3 tie recall to telemetry history. Option 4 keeps the default branch in the write path. This proposal avoids both.

   We would add two things. Neither depends on the branch decision, so both can ship as separate PRs.

   Add one read seam before the switch

   #484 was cheap because every reader already called getReportsDir(). learnings/ has no such function. Eleven call sites build the path by hand:

   src/
   ├── pull.ts:916                    reader
   ├── recall.ts:281                  reader
   ├── digest.ts:228                  reader
   ├── viz.ts:145,170                 reader
   ├── maintenance/paths.ts:33        reader
   ├── contribute.ts:53,198           writer, plus the index rebuild
   ├── import.ts:247                  writer
   ├── import-mr.ts:291               writer
   ├── ci/extract-mr.ts:116,205       writer
   ├── maintenance/prune.ts:102       writer, learnings/_archive
   └── utils/pending-learnings.ts:86  writer
   

   A missed call site does not throw. It reads an empty directory. Recall returns fewer results, and prune archives into a branch that nobody reads.

   The same list shows that contribute is not the only writer. import, import-mr, and the maintenance commands also create and move learnings. The issue does not list them.

   We would land a pure refactor first, with no branch change:

   export interface LearningsRoots {
     write: string;    // where new learnings go
     read: string[];   // precedence order, write root first
   }
   export function getLearningsRoots(localConfig: LocalConfig): LearningsRoots;

   buildIndex then takes learningsDirs: string[] and deduplicates by relative path. The first root wins. After that, the branch switch changes one function.

   The read list also answers the "do not migrate" rule. #484 could abandon the report files on main, because the next session regenerates them. Nobody regenerates a learning. If readers stop looking at the clone's learnings/, every note written before the switch drops out of recall. Keep that directory as the last read root, and nothing is copied, deleted, or lost.

   The read list also frees the branch shape. If the old tree stays readable, teamai-learnings can be an orphan branch that holds only learnings/. The worktree then carries no second copy of skills/, rules/, docs/, and teamai.yaml, which goes stale as soon as the branch exists.

   Make contribute offline-first

   pending-learnings/ is already a durable queue outside the clone. Make it the only write path:

    contribute
   -  write into <clone>/learnings/
   -  pushRepoDirectly(...)
   -  on failure: savePendingLearning(...)   # a second, different write path
   +  savePendingLearning(...)
   +  flushPendingLearnings()                # the only code that knows the branch

   Three facts about the code today:

   • pull.ts:127 discards the return value of flushPendingLearnings, and that function logs every failure at log.debug. No message in src/ tells the user that learnings are queued. A member without push rights queues notes forever and reads "Will retry on the next pull" every time. That member is the reason for this issue.
   • contributeSelf saves nothing when the push fails, so the note is lost. This issue routes every self-mode contribution through that path.
   • Two functions do the same write: pushRepoDirectly in contribute, and pushLearningToOrigin in the flush. The issue has to move both.

   With the queue as the write path, contribute never runs git. Self mode gets the durability that git mode has. The branch target lives in one function. We would also print the queue state during pull, for example 2 learnings pending (last error: ...).

   👍React with 👍1Reacted by Jeff
2. jeff-r2026

   added

   enhancementNew feature or requestNew feature or request

   on Sep 17, 2026
3. jeff-r2026

   added the

   Feature

   issue type on Sep 17, 2026
4. jeff-r2026 commented on Sep 17, 2026

   

   jeff-r2026

   on Sep 17, 2026

   CollaboratorAuthor

   More actions

   Thanks — this is the right read on both fronts. Decisions, so we can lock the implementation:

   1. Name & shape — confirmed. teamai-learnings, dedicated branch, direct push, reuse the worktree/lock/retry helper from src/utils/reports-branch.ts (#484 landed) without sharing REPORTS_BRANCH or the reports worktree.

   2. Orphan branch — agreed, changing the proposal. You're right that a non-orphan branch drags a second copy of skills/ rules/ docs/ teamai.yaml that goes stale the moment the branch exists. Make teamai-learnings an orphan branch holding only learnings/. We drop the "later merge-to-main is a normal PR" argument from the body — learnings don't need that path.

   3. Keep the old tree readable — agreed, this fixes a real data-loss bug. My "not read after the switch" line was wrong: reports regenerate, learnings don't, so cutting readers off from the clone's learnings/ would silently drop every pre-switch note out of recall. Fix as you describe: keep the old learnings/ as the last read root. Precedence = new orphan worktree first, old clone dir last, dedup by relative path. Still nothing copied or deleted — just kept readable. This is also what makes the orphan shape in (2) safe.

   4. No separate refactor PR — fold the read-seam into the one PR. Don't land getLearningsRoots() as a standalone pure-refactor step first; do the multi-root read seam and the branch switch together in a single PR. The { write, read[] } shape and buildIndex(learningsDirs: string[]) are still the right mechanism (they're what makes (3) work), and yes — cover the writers I missed in the body: import, import-mr, ci/extract-mr, maintenance/prune. Just don't split it across two PRs.

   5. Offline-first / queue-only — out of scope here, please open a separate issue. Making pending-learnings/ the single write path, routing self-mode through the durable queue, and surfacing queue state during pull (N learnings pending (last error: ...)) is a real gap — contributeSelf dropping notes on push failure and flushPendingLearnings only logging at debug both need fixing. But it's a separate change from the branch move and shouldn't gate it. Could you open a dedicated issue for it and link back here? Happy to review it there.

   Net change to the issue body: (a) branch becomes orphan, learnings/ only, (b) Acceptance drops "not read after the switch" and instead requires pre-switch notes stay recallable via the old read root, (c) offline-first moves out of scope to a follow-up. Everything else stands.
5. SaulMoro commented on Sep 17, 2026

   

   SaulMoro

   on Sep 17, 2026

   Collaborator

   More actions

   Agreed on all five, and thanks for the call on (3) — that was the part worth getting wrong out loud.

   Offline-first is now #615, out of this change's way. The PR for #485 and #486 lands the branch move, the multi-root read seam and the docs together, as you asked in (4).
6. SaulMoro

   added 2 commits that reference this issue on Sep 17, 2026

   fix(contribute): keep a contribution findable when nothing can be pub…

   ...

   3e61fb6

   fix(learnings): do not call a successful push a failure, and cap how …

   ...

   b386538
7. jeff-r2026

   added a commit that references this issue on Sep 17, 2026

   feat(learnings): write learnings to the teamai-learnings branch (#616)

   ...

   d4c57a0
8. jeff-r2026

   closed this as completedin #616on Sep 17, 2026
9. jimpablo

   added a commit that references this issue on Sep 23, 2026

   fix(members): read the default-branch roster as an inherited root aft…

   ...

   3e8dc3a
10. jeff-r2026

    added a commit that references this issue on Sep 23, 2026

    fix(members): read the default-branch roster as an inherited root aft…

    ...

    bc6943e
11. hsuchifeng

    added a parent issue on Oct 14, 2026

    • TeamAI Roadmap #647