feat(pop): mirror on-chain POP tasks into the KB (read-only catalog plugin) - #195
Open
hudsonhrh wants to merge 2 commits into
Open
feat(pop): mirror on-chain POP tasks into the KB (read-only catalog plugin)#195hudsonhrh wants to merge 2 commits into
hudsonhrh wants to merge 2 commits into
Conversation
…lugin) Adds a `pop` catalog plugin that mirrors a POP (Perpetual Organization Protocol) org's on-chain tasks into `context/tasks/POP-<chain>-<org>-<id>.md`, so the reminder engine, PM orchestrator, digests and the kb-ui /projects page all work on on-chain work for free. Read-only by construction: `POP_READONLY=1` is hardwired into the spawned `pop` process, which refuses to sign or broadcast even with a key present (capability removal, not policy). No private key is involved anywhere. Depends on `@poa-box/cli`, not `@poa-box/core` — the CLI declares ethers as a direct dependency so npm nests 5.7.2 under it and the host keeps ethers v6; core declares it as a peer, which npm would hoist to v6 and silently break its 427 v5-only call sites. Verified by install, and by driving the binary from an ESM host. Design (three properties do the work): - Chain is truth, and the FILE is the state. Each POP-*.md carries its own `pop_digest`, so there is no new table and the KB survives a DB restore. - Absence is never deletion. POP has no change cursor (updateTask/edit-meta/ cancelTask/claimTask bump no timestamp), the subgraph lags 30+ ids, and its query is capped at 50 projects / 1000 tasks with no truncation signal. So a possibly-capped listing deletes nothing, and a genuinely missing task is tombstoned for N consecutive exhaustive pulls before removal. - Human edits survive. Chain-owned frontmatter is overwritten; priority, custom tags, visibility and prose below the managed marker are preserved, following the mergeFrontmatter contract from discord-members-sync. Two read tiers: one `task list` per org per tick (~1.8s for 575 tasks) supplies everything existing KB consumers need; per-task `task view` adds description, submission, rejections and applications under a bounded, live-work-first budget whose remainder is logged rather than silently dropped. Terminal tasks are immutable on chain, so each is deep-read exactly once — that is what makes mirroring a 575-task archive affordable. Chain-authored prose is fenced as untrusted input. Anyone who can create a task controls its title and description, real POP descriptions read like work orders, and they land where an agent reads them; markers smuggled inside the text are neutralised rather than dropped. Off by default (policy-closed catalog plugin) and dormant without config. Verified end-to-end against a live org: 575 tasks, idempotent re-runs, failed and truncated pulls delete nothing, and human edits survive a real merge. Co-Authored-By: Claude <noreply@anthropic.com>
hudsonhrh
force-pushed
the
hudsonhrh/poa-cli-pr32-integration-plan
branch
from
August 4, 2026 17:25
a592436 to
eb9a42c
Compare
The new-org guide never mentioned catalog plugins, so there was no written answer to "does adopting labor.fun mean adopting POP?" (it does not — the catalog is dark until an org lists an id in enabledPlugins). Adds that section plus the POP example, and calls out the gating footgun: adding `enabledPlugins` at all — even as `[]` — flips gating ON, so an org with existing profile-dir plugins must list those too or they silently stop registering. Also warns at startup when an org omits `orgId`. It is optional today and falls back to the org NAME in the task identity URL, but that URL is meant to be immutable — it becomes the Linear attachment join key, and `attachmentsForURL` is stateless precisely because it never changes. Setting the real hex id later would rewrite every task's `pop_url` and orphan any link already attached. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Type of Change
.claude/skills/<name>/, no source changes)Description
Adds a
popcatalog plugin that mirrors a POP (Perpetual Organization Protocol) org's on-chain tasks intocontext/tasks/POP-<chain>-<org>-<id>.md, so the reminder engine, PM orchestrator, digests and the kb-ui/projectspage all work on on-chain work for free — it is read-only by construction, withPOP_READONLY=1hardwired into the spawnedpopprocess so it cannot sign or broadcast even if a key were present, and no private key is involved anywhere. It depends on@poa-box/clirather than@poa-box/corebecause the CLI declares ethers as a direct dependency (npm nests 5.7.2 under it and the host keeps ethers v6), whereas core declares it as a peer that npm would hoist to v6 and silently break. Three properties do the design work: chain is truth and each file carries its ownpop_digestso there is no new table; absence is never deletion (POP has no change cursor, the subgraph lags 30+ ids, and its query is capped at 50 projects / 1000 tasks with no truncation signal — so a possibly-capped listing deletes nothing and a missing task is tombstoned across several exhaustive pulls first); and human edits survive, with only chain-owned frontmatter overwritten. Reads are two-tier — onetask listper org per tick (~1.8s for 575 tasks) covers everything existing KB consumers need, while per-tasktask viewadds description/submission/rejections/applications under a bounded, live-work-first budget whose remainder is logged rather than silently dropped, and terminal tasks are immutable on chain so each is deep-read exactly once. Chain-authored prose is fenced as untrusted input, since anyone who can create a task controls its title and description and real POP descriptions read like work orders.Off by default (policy-closed catalog plugin) and dormant without config. Verified end-to-end against a live org (575 tasks, idempotent re-runs, failed and truncated pulls delete nothing, human edits survive a real merge); 110 plugin tests, 2137 repo-wide, typecheck clean. Eight review findings were validated against the bundled CLI's own source and fixed, each with a regression test confirmed by reverting the fix and watching the suite go red.
For Skills