Skip to content

[feat] Make the pending-learnings queue the write path for contribute, and surface it #615

Closed

Description

@SaulMoro

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:

  1. Single-repo mode can lose a contribution. contribute persists 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.

  2. A queued learning is invisible. pull discards the result of publishing the queue, and every failure inside it logs at log.debug. No message anywhere in src/ 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.

  3. Two write paths, two shapes. contribute writes 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 contribute writes the learning to pending-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 a teamai-learnings branch (direct push, no PR) #485 already gives the publisher a result that distinguishes published, already-present, busy and failed, 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 own git 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 recall serves.
  • teamai pull reports what it published and warns, with the reason, when anything is still queued.
  • teamai doctor carries a check for the queue with an actionable fix. It rides the existing registry, so doctor --json gets 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 recall still finds it.
  • The queue entry survives until the content is confirmed on origin, and the next teamai pull publishes it.
  • teamai pull says how many learnings are queued and why, when any are stuck.
  • teamai doctor reports the queue, and both stay silent when it is empty.
  • Contributing while a pull or push holds the partition sync lock leaves the queue for that run instead of racing it on the shared clone.
  • kind: http unchanged.

Out of scope

Activity

  1. SaulMoro commented on Sep 17, 2026

    @SaulMoro
    CollaboratorAuthor

    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 --noEmit clean, npx vitest run green at 3343 tests, and the built CLI against a bare remote whose update hook refuses the default branch — contribute offline, recall still finds the note, doctor reports the queue, one pull publishes it.

  2. jeff-r2026 commented on Sep 17, 2026

    @jeff-r2026
    Collaborator

    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 in pull + 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.

  3. added a commit that references this issue on Sep 17, 2026
    b89e3d5
  4. SaulMoro commented on Sep 17, 2026

    @SaulMoro
    CollaboratorAuthor

    #621 is up, rebased onto main now that #616 has merged, so it carries a single commit. contribute reads 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.

  5. added a commit that references this issue on Sep 18, 2026
    1f79b2d
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions