diff --git a/.claude/orchestration/execution-state.yaml b/.claude/orchestration/execution-state.yaml new file mode 100644 index 0000000..4d97b20 --- /dev/null +++ b/.claude/orchestration/execution-state.yaml @@ -0,0 +1,96 @@ +schema_version: 3 +artifact: citewire-orchestration-execution-state +as_of: "2026-08-23" +claim_status: Verified + +canonical: + repository: Openly-Useful/citewire + main_commit: e12d9b6e8efed725a085a32e935e63e35241859a + website: https://citewire.org/ + website_status: "HTTPS 200" + community_version: 0.2.0 + npm_latest: 0.1.0 + tests: 119 + release_checks: 5 + node_ci: [18, 22] + +merged_foundations: + pull_requests: [2, 3, 4, 6, 7, 8] + capabilities: + - source registry and rights policy + - RSS and MCP projections + - optional local Studio + - credential-reference and connector boundaries + - deterministic classifier calibration + - fail-closed editorial shadow engine + safety_boundary: "Sources and connectors are inert by default; classifier and editorial engine cannot publish." + +open_drafts: + orchestration: + repository: Openly-Useful/citewire + pull_request: 1 + state: "draft; refresh in progress" + openly_useful_link: + repository: Openly-Useful/openlyuseful.org + pull_request: 8 + head: e48d6069e33f84a85d41ad397bc4ef74d3906451 + state: "draft, clean, CI green" + karaya_link: + repository: MeekPhills/karayagroup + pull_request: 17 + head: 004a8e09cfe146324bfe481664a5b68c182dc6b2 + state: "draft, clean, CI green, read-aloud approval pending" + cloud: + repository: MeekPhills/citewire-cloud + pull_request: 1 + head: 69068275ca0e332e36304533aa0f6b5d2e291405 + state: "draft, clean, Node 18/22 green, undeployed" + community_pin: 10aee95ac95bb437b4607723cd20fa5c8f9d1879 + +linear: + launch_parent: "OU-143 In Progress" + completed_foundations: + - "OU-145 Done" + - "OU-180 Done" + - "OU-181 Done" + - "OU-182 Done" + - "OU-183 Done" + immutable_release: "OU-149 Todo" + karaya_truth: "KAR-69 In Progress" + +karaya_observation: + registered_sources: 49 + monitored_sources: 27 + directory_only_sources: 22 + visible_items_seven_days: 6 + newest_item_age_hours: 60.6 + cron: "POST /api/cron/ingest returned 200 at 15-minute cadence" + unknowns: + - source-level fetch results + - queue age + - held volume + - migration state + +protected_state: + untracked_owner_screenshots: 41 + dirty_worktrees: + - parked CiteWire prototype + - Karaya editorial-shadow proposal + - Karaya navigation work + rule: "Preserve exactly; never stage, clean, move, delete, or credit as completed work." + +next_safe_sequence: + - validate and keep orchestration PR 1 draft + - obtain separate merge approval for Openly Useful PR 8 + - obtain Luis read-aloud and merge approval for Karaya PR 17 + - complete KAR-69 read-only production truth + - sequence Karaya shadow policy, exceptions console, and reversible canary + - obtain separate immutable-release approval for OU-149 + +hard_stops: + - failed check or unexpected diff + - secret or protected asset + - paid-service decision + - provider, source, or connector activation + - migration or production data/configuration mutation + - merge, deployment, DNS change, tag, package publish, release, or registry submission without explicit approval diff --git a/.claude/orchestration/recovery-ledger.yaml b/.claude/orchestration/recovery-ledger.yaml new file mode 100644 index 0000000..e02615a --- /dev/null +++ b/.claude/orchestration/recovery-ledger.yaml @@ -0,0 +1,56 @@ +schema_version: 3 +artifact: citewire-orchestration-recovery-ledger +as_of: "2026-08-23" + +claim_status_legend: + Verified: "Reproduced locally or read directly from the current remote or public endpoint." + Historical: "Recorded evidence that must be refreshed before a mutation." + Unknown: "Not established; do not infer authority or safety." + +verified: + - id: REC-001 + claim: "Openly-Useful/citewire is the canonical public repository at main e12d9b6." + boundary: "Repository existence does not authorize release or registry actions." + - id: REC-002 + claim: "citewire.org serves the CiteWire landing page over HTTPS with status 200." + boundary: "No DNS or deployment change is authorized by this record." + - id: REC-003 + claim: "Community main passes 119 tests and five release checks with zero package dependencies." + boundary: "This is not publication evidence." + - id: REC-004 + claim: "Public source, Studio, connector, classifier, and editorial foundations are merged and inert by default." + boundary: "Do not activate providers, connectors, credentials, or publishing." + - id: REC-005 + claim: "Openly Useful PR 8 and Karaya PR 17 are current clean green drafts." + boundary: "Each merge remains separately owner-gated; Karaya also requires read-aloud approval." + - id: REC-006 + claim: "Cloud PR 1 is a clean undeployed draft at 6906827 with Node 18/22 CI green and the Community archive pinned to 10aee95." + boundary: "Do not deploy or migrate to npm before immutable Community publication." + - id: REC-007 + claim: "npm latest is citewire 0.1.0 and no CiteWire GitHub release or tag exists." + boundary: "OU-149 remains an immutable-release gate." + - id: REC-008 + claim: "Karaya cron requests returned 200 every 15 minutes while the newest visible item was about 60.6 hours old." + boundary: "Finish KAR-69 read-only truth before changing data, sources, thresholds, policy, or migrations." + - id: REC-009 + claim: "Forty-one untracked owner screenshots and unrelated dirty worktrees remain protected." + boundary: "Never stage, edit, move, clean, delete, or use them as an implementation baseline." + +unknowns: + - id: REC-401 + topic: "Karaya source-level failures, queue age, held volume, and migration state" + boundary: "Read-only investigation only under KAR-69." + - id: REC-402 + topic: "Cloud operator, tenants, support/privacy, retention, billing, credentials, and deployment" + boundary: "Separate owner decisions and account-isolation review required." + - id: REC-403 + topic: "Immutable npm, GitHub release, MCP registry, and catalog sequence" + boundary: "Separate explicit approval required for every irreversible step." + +safety_state: + contains_credentials: false + contains_private_transcript: false + contains_local_paths: false + provider_activation_authorized: false + publication_authorized: false + production_mutation_authorized: false diff --git a/.claude/orchestration/streams/WS-001.md b/.claude/orchestration/streams/WS-001.md new file mode 100644 index 0000000..f7b2dc4 --- /dev/null +++ b/.claude/orchestration/streams/WS-001.md @@ -0,0 +1,13 @@ +# WS-001 — Orchestration continuity + +- Status: active refresh. +- Dependencies: none. +- Ownership: `CLAUDE.md`, `PROJECT_HANDOFF.md`, + `CLAUDE_CODE_LAUNCH_PROMPT.md`, and `.claude/orchestration/`. +- Verified state: canonical main is `e12d9b6`; the previous orchestration + snapshot was stale and PR #1 remains draft. +- Done when: portable artifacts parse, describe exactly 17 streams, contain no + secrets or local paths, match current remote truth, and pass Node 18/22 CI. +- Next action: validate and push this continuity-only refresh. +- Stop for: product-code diff, secret, protected asset, failed check, merge, or + any external mutation beyond the already authorized tracking refresh. diff --git a/.claude/orchestration/streams/WS-002.md b/.claude/orchestration/streams/WS-002.md new file mode 100644 index 0000000..8e39c4d --- /dev/null +++ b/.claude/orchestration/streams/WS-002.md @@ -0,0 +1,12 @@ +# WS-002 — Canonical identity and authority + +- Status: complete. +- Dependencies: WS-001. +- Ownership: identity and governance metadata. +- Verified state: CiteWire is the public brand, `citewire` is the technical + token, and `Openly-Useful/citewire` is the canonical repository. +- Done when: repository, package, server metadata, documentation, and website + use the same identity. That condition is met on main. +- Next action: preserve identity consistency. +- Stop for: repository transfer, archive, rename, package publication, + registry submission, or Cloud operator inference without separate approval. diff --git a/.claude/orchestration/streams/WS-003.md b/.claude/orchestration/streams/WS-003.md new file mode 100644 index 0000000..918806f --- /dev/null +++ b/.claude/orchestration/streams/WS-003.md @@ -0,0 +1,12 @@ +# WS-003 — Repository route and history + +- Status: complete for the current public route. +- Dependencies: WS-002. +- Ownership: repository-route evidence only. +- Verified state: the canonical public repository exists under Openly Useful + and current main is reproducible at `e12d9b6`. +- Done when: the chosen public route is reachable and its current history is + preserved. No legacy archive or transfer is required by this checkpoint. +- Next action: none. +- Stop for: history rewrite, mirror, transfer, archive, deletion, or visibility + change without explicit approval and a rollback plan. diff --git a/.claude/orchestration/streams/WS-004.md b/.claude/orchestration/streams/WS-004.md new file mode 100644 index 0000000..e68c171 --- /dev/null +++ b/.claude/orchestration/streams/WS-004.md @@ -0,0 +1,12 @@ +# WS-004 — Community 0.2 candidate + +- Status: complete and unpublished. +- Dependencies: WS-002. +- Ownership: package and release-candidate metadata. +- Verified state: version `0.2.0` is merged on canonical main and passes 119 + committed tests plus five release checks. +- Done when: exact main passes isolated install, tests, release checks, package + inspection, syntax, diff, and Node 18/22 CI. +- Next action: keep unpublished until WS-008 receives exact approval. +- Stop for: failed check, version collision, tag, publish, release, or registry + action. diff --git a/.claude/orchestration/streams/WS-005.md b/.claude/orchestration/streams/WS-005.md new file mode 100644 index 0000000..32206ed --- /dev/null +++ b/.claude/orchestration/streams/WS-005.md @@ -0,0 +1,12 @@ +# WS-005 — CiteWire landing and HTTPS + +- Status: complete. +- Dependencies: WS-002 and WS-004. +- Ownership: `site/` and its committed regression test. +- Verified state: `https://citewire.org/` returns HTTPS 200 with the CiteWire + landing page and strict response headers. +- Done when: canonical content, HTTPS, assets, robots, sitemap, and outbound + links are healthy. The availability gate is met. +- Next action: none. +- Stop for: DNS, certificate, hosting, or deployment change without separate + owner approval. diff --git a/.claude/orchestration/streams/WS-006.md b/.claude/orchestration/streams/WS-006.md new file mode 100644 index 0000000..50740a5 --- /dev/null +++ b/.claude/orchestration/streams/WS-006.md @@ -0,0 +1,12 @@ +# WS-006 — Openly Useful CiteWire link + +- Status: ready draft, unmerged. +- Dependencies: WS-005. +- Ownership: the CiteWire card in `open-source.html` and its committed site + validator. +- Verified state: PR #8 head `e48d606` is clean, mergeable, and green. Its + exact two-file diff targets `https://citewire.org`. +- Done when: the focused diff is separately approved and merged. +- Next action: obtain merge approval. +- Stop for: expanded diff, invalid HTTPS, failed CI, merge, or deploy without + approval. diff --git a/.claude/orchestration/streams/WS-007.md b/.claude/orchestration/streams/WS-007.md new file mode 100644 index 0000000..20ddc44 --- /dev/null +++ b/.claude/orchestration/streams/WS-007.md @@ -0,0 +1,13 @@ +# WS-007 — Karaya CiteWire bridge + +- Status: ready draft, owner-gated. +- Dependencies: WS-005. +- Ownership: the bridge document, About-page CiteWire link, and committed + compliance regression. +- Verified state: PR #17 head `004a8e0` is clean and green; 432 tests, build, + registry, audit, compliance, and the live target passed. +- Done when: Luis approves the exact visible copy by read-aloud, then separately + approves merge and production verification. +- Next action: present the visible copy for approval. +- Stop for: visible copy without approval, protected screenshots, failed + check, merge, or deployment. diff --git a/.claude/orchestration/streams/WS-008.md b/.claude/orchestration/streams/WS-008.md new file mode 100644 index 0000000..3465fe5 --- /dev/null +++ b/.claude/orchestration/streams/WS-008.md @@ -0,0 +1,12 @@ +# WS-008 — Immutable Community release + +- Status: blocked on explicit owner approval. +- Dependencies: WS-003, WS-004, and WS-005. +- Ownership: release workflow, changelog, distribution, and release docs. +- Verified state: npm latest is `citewire@0.1.0`; no CiteWire tag or GitHub + release exists. Community `0.2.0` is not published. +- Done when: an approved tag, npm integrity and provenance, GitHub release, + support/security URLs, and registry records are independently verified. +- Next action: keep OU-149 Todo until exact immutable-step approval. +- Stop for: tag, npm publish, GitHub release, registry or catalog submission, + version collision, or missing provenance. diff --git a/.claude/orchestration/streams/WS-009.md b/.claude/orchestration/streams/WS-009.md new file mode 100644 index 0000000..8127630 --- /dev/null +++ b/.claude/orchestration/streams/WS-009.md @@ -0,0 +1,12 @@ +# WS-009 — Cloud archive-pin alignment + +- Status: complete, preserve-only. +- Dependencies: WS-001. +- Ownership: evidence only. +- Verified state: Cloud PR #1 head `6906827` pins Community commit `10aee95`, + passes 15 tests and Node 18/22 CI, and remains a clean undeployed draft. +- Done when: Cloud docs and lockfile agree without implying availability or + deployment. That condition is met. +- Next action: preserve the current draft. +- Stop for: provider, participant, credential, paid service, domain, + deployment, or runtime decision. diff --git a/.claude/orchestration/streams/WS-010.md b/.claude/orchestration/streams/WS-010.md new file mode 100644 index 0000000..6d4fced --- /dev/null +++ b/.claude/orchestration/streams/WS-010.md @@ -0,0 +1,13 @@ +# WS-010 — Cloud npm migration + +- Status: blocked on WS-008. +- Dependencies: WS-008. +- Ownership: Cloud `package.json` and `package-lock.json` only. +- Verified state: Cloud still uses the exact Community archive pin; the + required public npm `0.2.0` artifact does not exist. +- Done when: npm provenance and MCP identity are verified, then isolated + install, all tests, syntax, direct HTTP smoke, concurrent account-isolation, + diff, and Node 18/22 CI pass while Cloud stays draft and undeployed. +- Next action: retain the archive pin. +- Stop for: wrong provenance, lockfile surprise, failed account isolation, + publication, or deployment. diff --git a/.claude/orchestration/streams/WS-011.md b/.claude/orchestration/streams/WS-011.md new file mode 100644 index 0000000..e2032d2 --- /dev/null +++ b/.claude/orchestration/streams/WS-011.md @@ -0,0 +1,13 @@ +# WS-011 — Cloud private-alpha operations + +- Status: blocked on owner decisions. +- Dependencies: WS-002 and WS-009. +- Ownership: Cloud auth, HTTP, plan, tool, test, and owner-decision surfaces. +- Verified state: Cloud PR #1 is fail-closed, account-isolated, draft, and + undeployed. Operator, tenant, support/privacy, domain, retention, billing, + OAuth, participant, and rollback decisions remain unresolved. +- Done when: those decisions are approved and committed account-isolation and + security tests pass. Deployment remains a separate gate. +- Next action: maintain the decision checklist. +- Stop for: credential delivery, paid service, provider activation, privacy or + legal commitment, account-isolation failure, or deployment. diff --git a/.claude/orchestration/streams/WS-012.md b/.claude/orchestration/streams/WS-012.md new file mode 100644 index 0000000..d42dc09 --- /dev/null +++ b/.claude/orchestration/streams/WS-012.md @@ -0,0 +1,13 @@ +# WS-012 — Karaya production truth + +- Status: in progress, read-only. +- Dependencies: WS-001. +- Ownership: the dated production-truth evidence packet only. +- Verified state: 49 sources are registered, 27 monitored, 22 directory-only, + and six items appeared in seven days. The newest was about 60.6 hours old. + Ingest cron requests returned 200 every 15 minutes. +- Done when: deployed commit, migrations, source and circuit-breaker health, + queue age, held volume, corpus drift, and vendor provenance are reconciled. +- Next action: complete KAR-69 with authorized read-only evidence. +- Stop for: database write, migration, source or provider activation, policy or + threshold change, corpus rewrite, secret, or rights ambiguity. diff --git a/.claude/orchestration/streams/WS-013.md b/.claude/orchestration/streams/WS-013.md new file mode 100644 index 0000000..9c12a9b --- /dev/null +++ b/.claude/orchestration/streams/WS-013.md @@ -0,0 +1,13 @@ +# WS-013 — Community source and projection contract + +- Status: complete. +- Dependencies: WS-002 and WS-004. +- Ownership: Community registry, rights, RSS/MCP projections, schemas, tests, + and documentation. +- Verified state: merged PR #6 supplies versioned fail-closed source, rights, + attribution, canonical-link, RSS, and MCP contracts. +- Done when: invalid or ambiguous rights hold, defaults stay inert, and legacy + `news.*` behavior remains compatible. The committed suite proves this state. +- Next action: preserve compatibility. +- Stop for: provider activation, credentials, Karaya-specific policy, + publication, registry action, or breaking contract. diff --git a/.claude/orchestration/streams/WS-014.md b/.claude/orchestration/streams/WS-014.md new file mode 100644 index 0000000..1b1c182 --- /dev/null +++ b/.claude/orchestration/streams/WS-014.md @@ -0,0 +1,14 @@ +# WS-014 — Karaya deterministic shadow policy + +- Status: blocked on WS-012. +- Dependencies: WS-012. +- Ownership: future Karaya policy and non-publishing shadow paths. +- Verified state: Community has a merged generic fail-closed editorial engine, + but the Karaya-specific policy is not complete. The dirty Karaya proposal + remains uncredited and its migration is unapplied. +- Done when: deterministic replay, bounded run identity, complete pagination, + safe retries, convergent writes, rights traces, and no-publish behavior pass + against verified production schema. +- Next action: derive the ADR from KAR-69 truth, not the dirty proposal. +- Stop for: migration, threshold or model-cost choice, source activation, + automatic publishing, or failed replay. diff --git a/.claude/orchestration/streams/WS-015.md b/.claude/orchestration/streams/WS-015.md new file mode 100644 index 0000000..1257fcf --- /dev/null +++ b/.claude/orchestration/streams/WS-015.md @@ -0,0 +1,13 @@ +# WS-015 — Karaya exceptions console + +- Status: blocked on WS-014. +- Dependencies: WS-014. +- Ownership: future Karaya admin, UI, authorization, pause, and control paths. +- Verified state: public Studio is an optional local foundation. It is not the + Karaya approval console and does not supply Karaya authentication or policy. +- Done when: the console is exceptions-only, account-isolated, authorized, + auditable, globally pausable, accessible, and its visible tiers and reason + tags receive Luis's read-aloud approval. +- Next action: write the implementation specification after WS-014. +- Stop for: generic Studio substitution, routine review queue, unapproved copy, + missing pause proof, threshold choice, or data mutation. diff --git a/.claude/orchestration/streams/WS-016.md b/.claude/orchestration/streams/WS-016.md new file mode 100644 index 0000000..b669f1c --- /dev/null +++ b/.claude/orchestration/streams/WS-016.md @@ -0,0 +1,12 @@ +# WS-016 — Karaya reversible canary + +- Status: blocked on WS-015. +- Dependencies: WS-015. +- Ownership: future Karaya rollout configuration and canary runbooks. +- Verified state: no Karaya threshold change, autonomous publishing rollout, + canary, or rollback drill is authorized. +- Done when: Luis approves bounded metrics, monitoring, pause, rollback, and + canary; independent safety checks and recovery proof pass. +- Next action: no-change canary design only after WS-015. +- Stop for: missing metrics, absent pause proof, deploy, threshold/source/data + change, provider activation, paid service, or irreversible action. diff --git a/.claude/orchestration/streams/WS-017.md b/.claude/orchestration/streams/WS-017.md new file mode 100644 index 0000000..c9b24a5 --- /dev/null +++ b/.claude/orchestration/streams/WS-017.md @@ -0,0 +1,16 @@ +# WS-017 — Community product foundations + +- Status: complete and inert. +- Dependencies: WS-004 and WS-013. +- Ownership: Community, editorial, security, optional Studio, focused tests, + and product documentation. +- Verified state: merged PRs #6, #7, and #8 provide the source registry, + optional Studio, credential-reference and connector boundaries, calibrated + classifier, and fail-closed editorial shadow engine. Main passes 119 tests. +- Done when: all foundations remain read-only or shadow-only, default-disabled, + credential-safe, attribution-first, and unable to publish. That condition is + met on current main. +- Next action: activate nothing without an explicit product and security gate. +- Stop for: breaking contract, real credential storage, provider or connector + activation, hosted control-plane expansion, Karaya/Cloud leakage, + scheduling, publishing, release, registry, or deployment. diff --git a/.claude/orchestration/verification-evidence.md b/.claude/orchestration/verification-evidence.md new file mode 100644 index 0000000..7919516 --- /dev/null +++ b/.claude/orchestration/verification-evidence.md @@ -0,0 +1,61 @@ +# Verification evidence + +Evidence date: 2026-08-23, America/New_York. + +## Public CiteWire + +- Canonical main resolved to `e12d9b6e8efed725a085a32e935e63e35241859a`. +- PRs #2, #3, #4, #6, #7, and #8 are merged. +- The committed suite passed 119 tests. +- Release metadata passed five checks. +- Package metadata requires Node 18 or newer and has no dependencies. +- `https://citewire.org/` returned HTTPS 200 with strict response headers. +- npm reported `citewire@0.1.0` as latest. +- GitHub reported no tags or releases. +- GitHub vulnerability reporting returned 204, confirming it is enabled. + +## Draft integrations + +| Repository | PR | Head | Verified state | +| --- | ---: | --- | --- | +| Openly-Useful/citewire | #1 | refreshed by this branch | Draft; must pass Node 18/22 after push | +| Openly-Useful/openlyuseful.org | #8 | `e48d606` | Draft, mergeable, clean, validator and preview green | +| MeekPhills/karayagroup | #17 | `004a8e0` | Draft, mergeable, clean, 432 tests and CI green | +| MeekPhills/citewire-cloud | #1 | `6906827` | Draft, mergeable, clean, 15 tests and Node 18/22 green | + +## Karaya read-only observation + +- Registry API: 49 sources total, 27 monitored, 22 directory-only. +- Seven-day feed: six items. +- Newest visible publication: approximately 60.6 hours old. +- Production logs: `POST /api/cron/ingest` returned 200 at 15-minute cadence. +- Interpretation: the observed freshness gap is not evidence of a missing cron. + Source-level fetch results, queue age, held volume, and migration state remain + unknown. + +## Tracker reconciliation + +- OU-145 and OU-180 through OU-183 were read against their defined scopes, + commented with merged-commit and test evidence, and marked Done. +- OU-143 remains In Progress. +- OU-149 remains Todo. +- KAR-69 remains In Progress and received the read-only freshness observation. + +## Protected state + +- Forty-one untracked owner screenshots were left untouched. +- The parked CiteWire prototype, Karaya editorial-shadow proposal, and Karaya + navigation work were left untouched. +- No secret, credential, provider activation, migration, production mutation, + merge, deployment, DNS change, tag, publication, release, or registry action + occurred during this refresh. + +## Required refresh validation + +- Parse `execution-state.yaml`, `recovery-ledger.yaml`, and `work-graph.yaml`. +- Verify exactly 17 briefs and dependency references. +- Run isolated-cache install, 119 committed tests, five release checks, syntax + checks, secret/local-path scan, and `git diff --check`. +- Verify the PR-relative diff contains continuity artifacts only. +- Require fresh Node 18 and Node 22 CI before treating orchestration PR #1 as + green. diff --git a/.claude/orchestration/work-graph.yaml b/.claude/orchestration/work-graph.yaml new file mode 100644 index 0000000..16859e6 --- /dev/null +++ b/.claude/orchestration/work-graph.yaml @@ -0,0 +1,185 @@ +schema_version: 3 +artifact: citewire-orchestration-work-graph +as_of: "2026-08-23" +claim_status: Verified + +source_of_truth_order: + - latest explicit owner direction + - current reproducible behavior and committed tests + - fresh CI, HTTPS, GitHub, and Linear evidence + - reviewed git history and pull-request diffs + - repository documentation + - historical handoffs + +program_boundaries: + community: "Public, MIT, zero-dependency, read-only boundary, provider-neutral, attribution-first, inert by default." + studio: "Optional local management foundation; not a hosted control plane and not an authentication provider." + editorial: "Shadow-only, fail-closed, and unable to publish." + cloud: "Separate private account boundary; undeployed." + karaya: "Separate customized consumer; no private policy, credentials, state, or source configuration may leak into Community." + +protected_state: + - "41 untracked owner screenshots" + - "parked dirty CiteWire prototype" + - "dirty Karaya editorial-shadow proposal" + - "separate in-progress Karaya navigation work" + +streams: + - id: WS-001 + name: orchestration continuity + status: active_refresh + dependencies: [] + ownership: [CLAUDE.md, PROJECT_HANDOFF.md, CLAUDE_CODE_LAUNCH_PROMPT.md, .claude/orchestration/] + artifact: .claude/orchestration/work-graph.yaml + done: "Portable artifacts parse, contain exactly 17 streams, match current remote truth, contain no local paths or secrets, and pass Node 18/22 CI." + next: "Validate and keep PR 1 draft." + + - id: WS-002 + name: canonical identity and authority + status: complete + dependencies: [WS-001] + ownership: [docs/governance.md, package.json, server.json] + artifact: docs/governance.md + done: "CiteWire is public under Openly Useful with consistent package and website identity." + next: "Preserve identity; treat package and registry publication as separate gates." + + - id: WS-003 + name: repository route and history + status: complete_for_current_route + dependencies: [WS-002] + ownership: [repository metadata] + artifact: repository history + done: "Canonical public repository exists under Openly Useful and current main is reproducible." + next: "Do not transfer, archive, mirror, or rewrite history without separate approval." + + - id: WS-004 + name: Community 0.2 candidate + status: complete_unpublished + dependencies: [WS-002] + ownership: [package.json, package-lock.json, server.json, docs/providers.md] + artifact: package.json + done: "Version 0.2.0 is merged on main and passes 119 tests plus five release checks." + next: "Keep unpublished until WS-008 approval." + + - id: WS-005 + name: CiteWire landing and HTTPS + status: complete + dependencies: [WS-002, WS-004] + ownership: [site/, test/site.test.mjs] + artifact: site/README.md + done: "citewire.org returns the verified landing page over HTTPS 200." + next: "No DNS or deployment change required." + + - id: WS-006 + name: Openly Useful link + status: ready_draft_unmerged + dependencies: [WS-005] + ownership: [open-source.html, scripts/validate_site.py] + artifact: Openly-Useful/openlyuseful.org#8 + done: "Exact two-file draft diff validates, targets citewire.org, and CI is green." + next: "Obtain separate merge approval." + + - id: WS-007 + name: Karaya CiteWire bridge + status: ready_draft_owner_gate + dependencies: [WS-005] + ownership: [docs/citewire-product-bridge.md, site/src/pages/industry-news/about.astro, site/test/news-compliance.test.mjs] + artifact: MeekPhills/karayagroup#17 + done: "Exact three-file draft diff passes 432 tests, build, compliance, CI, and live target checks." + next: "Read visible copy aloud to Luis; obtain merge approval." + + - id: WS-008 + name: immutable Community release + status: blocked_owner_approval + dependencies: [WS-003, WS-004, WS-005] + ownership: [.github/workflows/release.yml, CHANGELOG.md, docs/releasing.md, docs/distribution.md] + artifact: docs/distribution.md + done: "Approved tag, npm provenance, GitHub release, and registry records are independently verified." + next: "OU-149 remains Todo; request exact approval for each irreversible step." + + - id: WS-009 + name: Cloud archive-pin alignment + status: complete_preserve_only + dependencies: [WS-001] + ownership: [] + artifact: MeekPhills/citewire-cloud#1 + done: "Cloud archive pin is 10aee95 and docs do not imply deployment." + next: "Preserve draft and undeployed state." + + - id: WS-010 + name: Cloud npm migration + status: blocked_on_WS_008 + dependencies: [WS-008] + ownership: [package.json, package-lock.json] + artifact: CiteWire Cloud lockfile + done: "Published npm provenance and MCP identity are verified; Cloud tests, direct HTTP smoke, and concurrent account-isolation tests pass on Node 18/22." + next: "Retain the archive pin." + + - id: WS-011 + name: Cloud private-alpha operations + status: blocked_owner_decisions + dependencies: [WS-002, WS-009] + ownership: [Cloud auth, HTTP, plans, tools, tests, owner decision docs] + artifact: Cloud alpha checklist + done: "Operator, account, auth, support, privacy, retention, billing, domain, participant, and rollback decisions are approved and account isolation passes." + next: "Do not deploy or activate providers." + + - id: WS-012 + name: Karaya production truth + status: in_progress_read_only + dependencies: [WS-001] + ownership: [read-only production truth packet] + artifact: KAR-69 + done: "Deployed commit, migrations, source health, circuit breakers, cron, queue, held volume, corpus drift, and vendor provenance are dated and reconciled without mutation." + next: "Resolve source-level fetch results, queue age, held volume, and migration state." + + - id: WS-013 + name: Community source and projection contract + status: complete + dependencies: [WS-002, WS-004] + ownership: [src/community/, docs/source-registry-and-rights.md, docs/rss-and-mcp-projections.md] + artifact: merged PR 6 + done: "Versioned registry, rights, attribution, canonical-link, RSS, and MCP projection contracts are merged and fail closed." + next: "Preserve backward compatibility and inert defaults." + + - id: WS-014 + name: Karaya deterministic shadow policy + status: blocked_on_WS_012 + dependencies: [WS-012] + ownership: [Karaya policy and non-publishing shadow paths] + artifact: Karaya shadow-policy ADR + done: "Deterministic replay, bounded run identity, complete pagination, convergence, rights traces, and no-publish behavior pass on verified production schema." + next: "Do not use or migrate the dirty proposal as a shortcut." + + - id: WS-015 + name: Karaya exceptions console + status: blocked_on_WS_014 + dependencies: [WS-014] + ownership: [Karaya admin, UI, authorization, pause, and controls] + artifact: Karaya exceptions-console runbook + done: "Exceptions-only console is authorized, accessible, auditable, account-isolated, globally pausable, and read-aloud approved." + next: "Do not substitute public Studio for Karaya authorization." + + - id: WS-016 + name: Karaya reversible canary + status: blocked_on_WS_015 + dependencies: [WS-015] + ownership: [Karaya rollout configuration and canary runbooks] + artifact: Karaya canary runbook + done: "Luis approves metrics, pause, rollback, and bounded canary; safety checks pass and recovery is proven." + next: "No production rollout or threshold change." + + - id: WS-017 + name: Community product foundations + status: complete_inert + dependencies: [WS-004, WS-013] + ownership: [src/community/, src/editorial/, src/security/, apps/studio/, focused tests and docs] + artifact: merged PRs 6, 7, and 8 + done: "Source registry, optional Studio, connector boundary, calibrated classifier, and fail-closed editorial shadow engine pass 119 committed tests." + next: "Do not activate connectors, credentials, providers, scheduling, or publishing." + +hard_stops: + - failed check, unexpected diff, secret, protected asset, or owner overlap + - merge, deployment, DNS change, tag, publish, release, or registry action without explicit approval + - paid service, provider/source/connector activation, migration, or production mutation + - visible Karaya copy without Luis read-aloud approval diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..736746c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,53 @@ +# CLAUDE.md + +Read `PROJECT_HANDOFF.md`, `CLAUDE_CODE_LAUNCH_PROMPT.md`, and every file in +`.claude/orchestration/` before acting. + +CiteWire Community is MIT licensed, zero-dependency, Node 18+ ESM, +provider-neutral, attribution-first, and read-only at its public boundary. +Default sources and connectors are inert until an operator explicitly enables +them. The classifier and editorial engine are shadow-only and cannot publish. +Credential material is represented only by opaque references and must never be +stored in the public registry, logs, fixtures, or continuity artifacts. + +Cloud and Karaya are separate consumers with separate account and policy +boundaries. Never copy their credentials, source configuration, editorial +policy, private state, or account data into Community. + +## Current verified baseline + +- Canonical repository: `Openly-Useful/citewire`. +- Canonical main: `e12d9b6e8efed725a085a32e935e63e35241859a`. +- Public PRs #2, #3, #4, #6, #7, and #8 are merged. +- `https://citewire.org/` returns HTTPS 200 with the verified landing page. +- Main passes 119 committed tests and five release-metadata checks. +- The public product foundations now include the source registry, rights + policy, RSS and MCP projections, optional Studio, credential-reference and + connector boundaries, calibrated classifier, and fail-closed editorial + shadow engine. +- Nothing in this baseline proves a package, registry, provider, connector, + production editorial rollout, or automatic publication is active. + +## Active gates + +- Draft orchestration PR #1 may be refreshed and validated, but not merged + without separate approval. +- Openly Useful PR #8 and Karaya PR #17 are current, green, clean drafts. Keep + both unmerged unless their owner gates are separately satisfied. +- Cloud PR #1 is a clean draft pinned to Community commit `10aee95`; it remains + undeployed and account-isolated. +- npm still reports `citewire@0.1.0`; Community `0.2.0` is not published. +- Karaya automation remains a separate workstream. Public cron requests return + HTTP 200 every 15 minutes, but source-level fetch health, queue age, held + volume, and migration state remain unverified. +- Preserve the 41 untracked owner screenshots and every unrelated dirty + worktree exactly as found. + +## Hard stops + +Stop for a failed check, unexpected diff, secret, owner overlap, protected +asset, paid-service decision, provider or connector activation, migration, +production data/configuration change, merge, tag, package or registry publish, +release, deployment, DNS change, or any irreversible action without explicit +owner approval. Visible Karaya copy remains gated on Luis's read-aloud +approval. diff --git a/CLAUDE_CODE_LAUNCH_PROMPT.md b/CLAUDE_CODE_LAUNCH_PROMPT.md new file mode 100644 index 0000000..03789af --- /dev/null +++ b/CLAUDE_CODE_LAUNCH_PROMPT.md @@ -0,0 +1,28 @@ +# Claude Code launch prompt + +Read `CLAUDE.md`, `PROJECT_HANDOFF.md`, and every file under +`.claude/orchestration/` in full before acting. + +Continue from canonical CiteWire main commit +`e12d9b6e8efed725a085a32e935e63e35241859a` and first revalidate remote heads, +CI, HTTPS, and the working tree. Treat the public source registry, RSS/MCP +projections, optional Studio, connector boundary, calibrated classifier, and +fail-closed editorial shadow engine as merged foundations. Do not recreate +them from parked prototypes. + +Keep orchestration PR #1, Openly Useful PR #8, Karaya PR #17, and Cloud PR #1 +draft unless Luis separately approves the relevant merge. Do not deploy, +change DNS, activate sources/providers/connectors, apply migrations, alter +production data or configuration, tag, publish npm, create a GitHub release, +or submit a registry. Visible Karaya copy requires Luis's read-aloud approval. + +Use committed regression tests, routine smoke tests, and account-isolation +terminology. Preserve every untracked owner screenshot and unrelated dirty +worktree. Stop immediately for a failed check, unexpected diff, secret, +protected asset, paid-service decision, owner overlap, or irreversible action +without explicit approval. + +The next product-side work is Karaya-specific and sequential: finish KAR-69 +read-only production truth, then produce the deterministic non-publishing +policy, exceptions-only console, and reversible canary. The next public launch +gate is OU-149, which remains blocked on explicit immutable-release approval. diff --git a/PROJECT_HANDOFF.md b/PROJECT_HANDOFF.md new file mode 100644 index 0000000..78dfcda --- /dev/null +++ b/PROJECT_HANDOFF.md @@ -0,0 +1,87 @@ +# CiteWire program handoff + +Verified 2026-08-23 in America/New_York. This portable checkpoint records +reproducible repository, GitHub, Linear, CI, HTTPS, and read-only production +observations. It contains no credentials, private transcript, local path, or +machine-specific identifier. + +## Outcome + +CiteWire is now a public Openly Useful project with a live canonical website +and merged, inert product foundations. The remaining work is activation and +integration work behind explicit gates, not creation of the core foundations. + +| Area | Verified state | Next gate | +| --- | --- | --- | +| Community | Main `e12d9b6`; 119 tests; 5 release checks | Keep contracts backward-compatible | +| Website | `https://citewire.org/` returns HTTPS 200 | None for availability | +| Source registry | Merged; rights metadata and defaults are fail-closed | Operator-controlled enablement only | +| RSS and MCP | Merged projections with attribution and canonical links | No provider activation by default | +| Studio | Optional local management foundation merged | No hosted control plane or real credentials | +| Connectors | Credential-reference and endpoint-policy boundaries merged | Explicit operator setup and security review | +| Classifier | Deterministic calibration foundation merged | Shadow evaluation before any policy change | +| Editorial engine | Fail-closed shadow state machine merged | No automatic publishing | +| npm and registries | npm latest is `0.1.0`; no tag or release | Separate immutable-release approval | +| Cloud | Draft PR #1, head `6906827`, 15 tests, Node 18/22 green | Remain undeployed; later npm migration | +| Openly Useful link | Draft PR #8, head `e48d606`, clean and green | Separate merge approval | +| Karaya link | Draft PR #17, head `004a8e0`, 432 tests and CI green | Luis read-aloud approval, then merge approval | +| Karaya automation | KAR-69 remains In Progress | Complete read-only production truth first | + +## Repository and tracker truth + +- Public foundation PRs #6, #7, and #8 merged into canonical main on + 2026-08-16. Earlier identity, release-candidate, and landing work landed via + PRs #2, #3, and #4. +- OU-145 and OU-180 through OU-183 are Done because their defined inert + foundation scopes are present on main and verified by the committed suite. +- OU-143 remains In Progress as the launch parent. +- OU-149 remains Todo because package publication and ecosystem distribution + are immutable, separately approved actions. +- The legacy private Karaya integration remains a customized consumer and does + not define Community policy. + +## Karaya production observation + +Read-only verification on 2026-08-23 found 49 registered sources, 27 monitored +sources, and 22 directory-only sources. Six items were visible in the seven-day +window. The newest published item was approximately 60.6 hours old. Production +logs showed successful `POST /api/cron/ingest` requests at 15-minute cadence, +so the freshness gap is not evidence of a missing cron. Source-level fetch +results, queue age, held volume, and migration state remain unknown. Continue +KAR-69 before changing policy, thresholds, sources, or data. + +## Protected state + +- Preserve 41 untracked owner screenshots. Do not stage, move, edit, clean, or + delete them. +- Preserve the dirty Karaya editorial-shadow proposal without applying its + migration or granting completion credit. +- Preserve the dirty parked CiteWire prototype without staging or merging it. +- Preserve the separate in-progress Karaya navigation worktree. + +## Next safe sequence + +1. Validate and keep this orchestration refresh as draft PR #1. +2. Obtain separate approval before merging Openly Useful PR #8. +3. Read the exact visible Karaya PR #17 copy aloud to Luis and obtain approval + before merge or production verification. +4. Complete KAR-69 read-only production truth. Then design Karaya shadow + policy, exceptions console, and reversible canary in that order. +5. Treat Community `0.2.0` package publication, GitHub release, MCP registry, + connector activation, Cloud deployment, and automatic editorial publishing + as separate immutable or production-changing gates. + +## Validation commands + +```sh +npm ci --cache "$(mktemp -d)" +npm test +npm run release:check +find src test apps -type f \( -name '*.js' -o -name '*.mjs' \) -print0 \ + | xargs -0 -n1 node --check +git diff --check +``` + +Parse both orchestration YAML files, verify exactly 17 stream briefs, and +compare the PR against current main before pushing. CI must pass on Node 18 and +Node 22. Do not create ad hoc regression artifacts.