Repository navigation
[feat] Make the pending-learnings queue the write path for contribute, and surface it #615
Description
Related
Split out of #485 at the maintainer's request: "Making pending-learnings/ the single write path, routing self-mode through the durable queue, and surfacing queue state during pull is a real gap... But it's a separate change from the branch move and shouldn't gate it."
Problem
pending-learnings/ is a durable queue that already sits outside the clone, where a reset --hard cannot reach it. It is the fallback, not the write path, and nothing ever mentions it.
Three concrete gaps, all still true after #485:
-
Single-repo mode can lose a contribution.
contributepersists a durable copy only on the independent-clone path. In single-repo mode a rejected push leaves nothing behind: the note exists only in the temporary file the caller passed to--file. -
A queued learning is invisible.
pulldiscards the result of publishing the queue, and every failure inside it logs atlog.debug. No message anywhere insrc/tells a member that learnings are waiting. Someone whose pushes are refused queues notes indefinitely and is told each time that the next pull will retry. -
Two write paths, two shapes.
contributewrites and publishes; the pull-time retry writes and publishes again through a different call. Contributing is not one operation with one failure mode.
Proposal
Make the queue the write path, not the fallback.
teamai contributewrites the learning topending-learnings/and asks one function to publish it. Contribute itself runs no git command.- A queue entry is dropped only once its content is confirmed on origin. Write
learnings/to ateamai-learningsbranch (direct push, no PR) #485 already gives the publisher a result that distinguishespublished,already-present,busyandfailed, so this is a read of an existing signal. - Single-repo mode goes through the same queue, which is what closes gap 1. The queue lives under
.teamai/there, gitignored, so it never shows up in the user's owngit status. - The queue is indexed ahead of the published roots, so a contribution is recallable the moment it is written, online or not, and a queued edit of a published learning is the copy
recallserves. teamai pullreports what it published and warns, with the reason, when anything is still queued.teamai doctorcarries a check for the queue with an actionable fix. It rides the existing registry, sodoctor --jsongets it for free.
No new CLI command, and no change to where a learning goes: that is #485's business.
Acceptance
- A rejected push keeps the note in every mode, single-repo included, and
teamai recallstill finds it. - The queue entry survives until the content is confirmed on origin, and the next
teamai pullpublishes it. teamai pullsays how many learnings are queued and why, when any are stuck.teamai doctorreports the queue, and both stay silent when it is empty.- Contributing while a
pullorpushholds the partition sync lock leaves the queue for that run instead of racing it on the shared clone. kind: httpunchanged.
Out of scope
- Where learnings are written (Write
learnings/to ateamai-learningsbranch (direct push, no PR) #485) teamai pushof skills / rules / docs / env / agents- CI
extract-mr --mode write
Activity
SaulMoro commentedon Sep 17, 2026
The branch is ready on
SaulMoro:feat/learnings-queue-615, stacked on #616 because it touches the same files. I'll open the PR once #616 merges, so the diff shows only this change.Verified on that branch:
npx tsc --noEmitclean,npx vitest rungreen at 3343 tests, and the built CLI against a bare remote whoseupdatehook refuses the default branch — contribute offline,recallstill finds the note,doctorreports the queue, onepullpublishes it.fix(contribute): keep a contribution findable when nothing can be pub…
feat(contribute): make the pending queue the write path, and say when…
feat(contribute): make the pending queue the write path, and say when…
jeff-r2026 commentedon Sep 17, 2026
Ack — this is exactly the follow-up I asked for in #485, and the scope is right: make
pending-learnings/the write path, route single-repo through it, and surface the queue inpull+doctor.One sequencing note: this builds on #485's publisher result (
published/already-present/busy/failed), so land #485 first, then #615 on top. The two don't overlap in files otherwise — #485 owns where learnings go, #615 owns how contribute writes and reports them — so once #485 is in, this can go straight to a PR. Looking forward to it.feat(learnings): write learnings to the teamai-learnings branch (#616)
feat(contribute): make the pending queue the write path, and say when…
SaulMoro commentedon Sep 17, 2026
#621 is up, rebased onto main now that #616 has merged, so it carries a single commit.
contributereads the publisher result to decide whether a queue entry can be dropped, exactly the sequencing you described.One note on the no-overlap point. Nine of the ten files are queue territory. The tenth is
learnings-roots.ts, and it is five lines of comment with no code, recording why the queue is not one of the roots. Say the word and I drop it, the PR body explains the same thing.feat(contribute): make the pending queue the write path, and say when…