diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..51487a1b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,13 @@ +## Summary + + + +## Verification + + + +## Contributor agreement + +Signing on behalf of a legal entity (leave blank if accepting individually): + +- [ ] I have read and agree to the [RememberStack Contributor License Agreement v1.0](https://github.com/writeitai/remember-stack/blob/main/CLA.md). diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml new file mode 100644 index 00000000..92f1d285 --- /dev/null +++ b/.github/workflows/cla.yml @@ -0,0 +1,44 @@ +name: Contributor agreement + +on: + pull_request_target: + types: [opened, edited, reopened, synchronize] + +permissions: {} + +jobs: + cla: + name: CLA + runs-on: ubuntu-latest + timeout-minutes: 2 + steps: + # Security invariant: pull_request_target evaluates only event metadata. It must + # never check out, import, or execute code from the untrusted pull-request ref. + - name: Verify contributor assent + env: + PR_AUTHOR: ${{ github.event.pull_request.user.login }} + PR_BODY: ${{ github.event.pull_request.body }} + run: | + python3 - <<'PY' + import os + + author = os.environ.get("PR_AUTHOR", "") + if author in {"dependabot[bot]", "github-actions[bot]"}: + raise SystemExit(0) + + expected = ( + "- [x] I have read and agree to the " + "[RememberStack Contributor License Agreement v1.0]" + "(https://github.com/writeitai/remember-stack/blob/main/CLA.md)." + ) + lines = { + line.strip().casefold() + for line in os.environ.get("PR_BODY", "").splitlines() + } + if expected.casefold() not in lines: + print( + "::error::Read CLA.md and check the exact contributor-agreement " + "box in the pull-request body." + ) + raise SystemExit(1) + PY diff --git a/CLA.md b/CLA.md new file mode 100644 index 00000000..d531da0b --- /dev/null +++ b/CLA.md @@ -0,0 +1,197 @@ +# RememberStack Contributor License Agreement + +Version 1.0 — 23 July 2026 + +Thank you for contributing to RememberStack. This Contributor License Agreement +("Agreement") documents the rights that You grant to WriteIt.ai s.r.o., IČO 04518136, +with its registered office at Na Folimance 2155/15, Vinohrady, 120 00 Praha 2, +Czech Republic ("We", "Us", or "WriteIt.ai"). + +This is a legally binding agreement. You accept it electronically when You submit a +RememberStack pull request containing the checked assent required by the repository's +pull-request template. If You do not agree, do not check that box or submit the work for +inclusion. + +## 1. Definitions + +**"You"** means the authenticated GitHub pull-request author accepting this Agreement +as an individual. If that author identifies a legal entity in the pull request's +"Signing on behalf of" field, "You" instead means that entity and the author represents +that they are authorized to bind it. + +**"Contribution"** means a work of authorship that You Submit to Us for inclusion in +RememberStack and in which You own, or have authority to license, the applicable +Copyright. It excludes material conspicuously marked "Not a Contribution" and +third-party material that You identify as such. + +**"Copyright"** means copyright, moral, neighboring, and similar rights protecting +works of authorship for the full term of those rights. + +**"Material"** means RememberStack and any successor, renamed, split, combined, or +derivative project controlled by Us into which Your Contribution is incorporated. + +**"Submit"** means intentionally sending a Contribution to a repository, issue tracker, +or other collaboration system managed by Us for the purpose of discussing or improving +the Material. + +**"Self-Host"** means to install and operate the Material, in source or object form and +with or without modification, on infrastructure selected or controlled by the recipient +for that recipient's own use. It includes personal, research, nonprofit, and internal +commercial production use. It does not include offering the Material's functionality to +third parties as a hosted or managed service. + +**"Qualifying License"** means a license under which every recipient has perpetual +rights, without paying a license fee to Us or an affiliate and without being required +to purchase support or another service, to: + +1. obtain the corresponding source code for the Material; +2. reproduce and modify the Material; +3. redistribute the Material and modifications, in source or object form, for others + to Self-Host; and +4. Self-Host and operate the Material without limits based on users, seats, instances, + data volume, or duration. + +A Qualifying License may require attribution, publication of modifications, source-code +availability, or other reciprocal conditions. It may also restrict offering the +Material as a hosted or managed service to third parties. Charges for hosting, support, +consulting, or other services do not by themselves prevent a license from qualifying. + +## 2. Grant of rights + +### 2.1 Copyright license + +You retain ownership of the Copyright in Your Contribution and remain free to use or +license it independently. + +To the maximum extent permitted by law, You grant Us a perpetual, worldwide, +non-exclusive, transferable (subject to Section 6.3), royalty-free, irrevocable +copyright license, with the right to sublicense through multiple tiers, to reproduce, +modify, prepare derivative works of, publicly display, publicly perform, distribute, +and otherwise use Your Contribution as part of the Material. + +### 2.2 Patent license + +For patent claims that You own, control, or have the right to license now or in the +future, You grant Us a perpetual, worldwide, non-exclusive, transferable (subject to +Section 6.3), royalty-free, irrevocable patent license, with the right to sublicense +through multiple tiers, to make, have made, use, offer to sell, sell, import, and +otherwise transfer Your Contribution and Your Contribution in combination with the +Material. + +This license applies only to claims necessarily infringed by Your Contribution alone or +by its combination with the Material. + +### 2.3 Bounded outbound licensing + +We covenant that, when We license Your Contribution to third parties as part of the +Material, We will do so only under one or more Qualifying Licenses. The Apache License, +Version 2.0 used by RememberStack on the date of this Agreement is a Qualifying License. + +This covenant permits a future license to protect a hosted-service business, but it +does not permit Us to remove the source-availability and free Self-Hosting rights +defined above. Once We release a version under a Qualifying License, We will not revoke +or narrow the rights already granted under that license. Versions already released +under the Apache License, Version 2.0 remain available under that license. + +This covenant does not restrict Our use of the Contribution, including using it to +provide hosted services without granting third parties a copyright license to the +Material. It does not require Us to publish a Contribution that We have not incorporated +into the Material. + +The grants in Sections 2.1 and 2.2 are not conditional on this covenant and do not +terminate automatically if We breach it. A breach of this Section 2.3 is a material +breach of this Agreement. You may seek injunctive relief, specific performance, and any +other remedy available under applicable law to stop or remedy licensing that violates +this covenant. A breach does not invalidate a license previously granted to a recipient +under a Qualifying License. + +### 2.4 Moral rights + +To the maximum extent permitted by law, You waive and agree not to assert moral rights +in the Contribution against Us, Our successors, or Our direct or indirect licensees. +Where waiver is not permitted, You grant the broadest license or consent permitted by +law to exercise those rights consistently with this Agreement. + +### 2.5 Reservation and acceptance + +You reserve every right not expressly granted by this Agreement. We are not required to +accept or use any Contribution. + +## 3. Your representations + +You represent that: + +1. You have legal authority to enter into this Agreement and make these grants. +2. The Contribution is Your original work, or You otherwise own or control the rights + needed to grant the licenses in Section 2. +3. These grants do not violate an agreement with another party, including Your + employer. If another person or entity owns or controls the relevant rights, You have + obtained its authorization before Submitting. +4. You have identified any third-party material included in the Contribution and + complied with its license. Material You do not have authority to license under this + Agreement must be clearly marked "Not a Contribution." +5. The Contribution is not confidential information that You or another party expects + Us to keep confidential. +6. If You are accepting for a legal entity, You are authorized to bind that entity. If + You are under the age required to enter this Agreement, Your parent or legal guardian + has accepted it for You. + +## 4. Disclaimer + +EXCEPT FOR THE EXPRESS REPRESENTATIONS IN SECTION 3, THE CONTRIBUTION IS PROVIDED +"AS IS". TO THE MAXIMUM EXTENT PERMITTED BY LAW, YOU DISCLAIM ALL EXPRESS OR IMPLIED +WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND +NON-INFRINGEMENT. + +## 5. Limitation of liability + +TO THE MAXIMUM EXTENT PERMITTED BY LAW, NEITHER YOU NOR WE WILL BE LIABLE TO THE OTHER +UNDER THIS AGREEMENT FOR LOST PROFITS, LOST SAVINGS, LOSS OF DATA, OR INDIRECT, +SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES, REGARDLESS OF THE THEORY OF +LIABILITY. + +## 6. Miscellaneous + +### 6.1 Governing law + +This Agreement is governed by the laws of the Czech Republic, excluding its +conflict-of-laws rules. The United Nations Convention on Contracts for the +International Sale of Goods does not apply. + +### 6.2 Entire agreement + +This Agreement is the entire agreement between You and Us concerning Your +Contributions and supersedes prior understandings about those Contributions. + +### 6.3 Transfer + +We may transfer this Agreement and the rights granted under it to an affiliate or to a +successor or acquirer of all or substantially all of the Material or the business that +maintains it, but only if that recipient agrees in writing to assume Our obligations, +including Section 2.3. You may transfer this Agreement only with Our written consent. +Existing Qualifying Licenses and permitted sublicenses remain effective after a +transfer. + +### 6.4 Waiver and severability + +A failure to enforce a provision is not a waiver of that provision. If a provision is +unenforceable, it will be adjusted only as far as necessary to make it enforceable +while preserving its intent; the remaining provisions stay effective. + +### 6.5 Revisions + +Each published revision of this Agreement has a version number. A revision applies only +to Contributions for which You assent to that revision; it does not retroactively +expand grants made under an earlier version. + +### 6.6 Electronic record + +Your authenticated GitHub account, the pull request containing Your checked assent and +any "Signing on behalf of" entry, and GitHub's associated repository history form the +electronic record of Your acceptance. + +This Agreement is adapted from the Harmony Contributor Agreement Template, Version 1.0, +licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). It has been +materially modified for RememberStack, including its bounded outbound-license condition, +electronic acceptance, and Czech governing law. Project Harmony does not endorse this +Agreement. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..81c5cf2c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to RememberStack + +Thank you for helping improve RememberStack. Keep changes focused: for substantial work, +open an issue first so the scope and design boundary are clear before implementation. + +## Development + +The repository uses `uv` and supports Python 3.12 through 3.14. + +```bash +uv sync --locked --python 3.14 +uv run ruff check src/ +uv run ruff format --check src/ +uv run pyright src/ --pythonversion 3.14 +uv run pytest src/tests -q +``` + +Run the smallest relevant test set while iterating, then the complete checks appropriate +to the change before requesting review. User-facing behavior changes must update the +corresponding documentation in the same pull request. + +## Contributor agreement + +RememberStack is currently distributed under the Apache License, Version 2.0. Before a +human-authored pull request can merge, its author must accept the +[RememberStack Contributor License Agreement](CLA.md). + +The agreement is a license, not a copyright assignment: You keep ownership of Your +Contribution. It gives WriteIt.ai s.r.o. the rights needed to maintain and distribute +RememberStack, including a bounded ability to change the outbound license. Any such +license must continue to make source available and permit free self-hosting as defined +in the agreement. + +The pull-request template contains the required assent checkbox. The `CLA` job fails +until the exact box is checked; once that status is required in `main` protection, a +failure blocks merge. A later agreement version requires fresh assent and does not +retroactively expand an earlier grant. + +If Your employer or another entity owns the work, only accept on its behalf if You are +authorized to bind it, and identify that entity in the pull-request field. The assent +covers only work that the accepting individual or entity owns or is authorized to +license. Split contributions into separate pull requests when copyrightable work from +another author is not covered by that authority. Identify third-party material and its +license in the pull request; do not represent third-party work as Your Contribution. + +## Pull requests + +- Keep each pull request limited to one coherent change. +- Explain the behavior change and the verification performed. +- Preserve unrelated user changes and generated artifacts. +- Do not include secrets, private data, or material You cannot license. +- Expect maintainers to request changes that reduce complexity or scope. + +Project names and logos are governed separately by the +[RememberStack Trademark Policy](TRADEMARKS.md). diff --git a/README.md b/README.md index 0fd0d680..06ca644a 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ distill them into progressively more abstract, navigable knowledge — while kee auditable by humans. Scale is a requirement, not an aspiration: it is meant to still be useful at a million documents. -> **Pre-release software.** Phases 0–6 and most of Phase 7 are implemented and tested. Release -> automation exists, but the owner-side legal, governance, and registry setup gates are not -> complete, so no public package or container release exists yet. The fresh-deployment Docker +> **Pre-release software.** Phases 0–7 are implemented and tested. Release automation, trusted +> publishing, and tag protection are in place; activation of the bounded contributor-agreement +> check and the first public tag remain. The fresh-deployment Docker > Compose skeleton is documented under > [Self-host deployment](website/src/app/docs/deployment/page.mdx); it proves PostgreSQL, MinIO, > API ingestion, and the first two E0 worker stages, not a production rollout. The build follows diff --git a/RELEASING.md b/RELEASING.md index e8214777..07510b90 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -6,11 +6,13 @@ It accepts only tags exactly matching `vMAJOR.MINOR.PATCH`. ## One-time owner setup -Complete these steps in order: +The owner setup is in its final activation step: -1. Finish the focused name clearance and put the bounded CLA in place. These are governance - gates, not release-workflow features. -2. Confirm the GitHub repository is `writeitai/remember-stack`, then update each existing clone: +1. D77 records explicit acceptance of the preliminary naming risk. `CLA.md`, the trademark policy, + pull-request template, and `CLA` workflow land together; after merge, make the emitted `CLA` + status a required `main` check with administrator enforcement before accepting an outside + contribution or creating the first release tag. +2. The GitHub repository is `writeitai/remember-stack`. Update each existing clone if needed: ```bash git remote set-url origin git@github.com:writeitai/remember-stack.git @@ -20,9 +22,9 @@ Complete these steps in order: RememberStack and the Python distribution/import remain `rememberstack`. GitHub redirects ordinary repository and Git traffic after a rename, but the final name must be in place before configuring PyPI because the trusted identity includes the repository name. -3. In the GitHub repository, create an environment named `pypi`. Add yourself as a required - reviewer so a tag cannot publish to PyPI without an explicit approval. -4. Create a PyPI account, enable two-factor authentication, and add a +3. The GitHub environment `pypi` requires an owner review, so a tag cannot publish to PyPI without + explicit approval. +4. The PyPI account uses two-factor authentication and has a [pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) with these exact values: @@ -36,7 +38,8 @@ Complete these steps in order: A pending publisher does not reserve the PyPI name. Configure it only after the repository rename and publish promptly once the release gates are clear. -5. Protect tags matching `v*` so only maintainers can create or update release tags. +5. The active `Protect release tags` ruleset restricts creation, update, and deletion of tags + matching `v*` to repository administrators. No PyPI password or long-lived API token belongs in GitHub secrets. The workflow requests a short-lived OpenID Connect credential and grants `id-token: write` only to the PyPI job. diff --git a/TRADEMARKS.md b/TRADEMARKS.md new file mode 100644 index 00000000..f9f9d2a6 --- /dev/null +++ b/TRADEMARKS.md @@ -0,0 +1,54 @@ +# RememberStack Trademark Policy + +RememberStack is open-source software. The Apache License, Version 2.0 grants broad +copyright and patent permissions, but it does not grant a general right to use project +trademarks. + +This policy covers the names **RememberStack** and **remember.dev**, associated logos +and visual marks, and confusingly similar variations (the "Marks"). The Marks are owned +by WriteIt.ai s.r.o. This policy does not claim that every Mark is registered in every +jurisdiction. + +## Uses that do not require permission + +You may: + +- truthfully refer to RememberStack and link to `https://remember.dev`; +- state that software is compatible with, built with, or based on RememberStack, so long + as the statement does not imply sponsorship or endorsement; +- use the package name `rememberstack`, command name `remember`, and documented API + identifiers as technically necessary for installation, interoperability, or accurate + documentation; +- redistribute unmodified official RememberStack releases using their original name; + and +- use the word mark in community discussion, news, tutorials, and noncommercial events + that do not imply official status. + +When practical, use wording such as "based on RememberStack" or "compatible with +RememberStack" and state that the project is not affiliated with or endorsed by +WriteIt.ai. + +## Uses that require written permission + +Ask first before: + +- using a Mark as the primary name of a company, product, service, package, domain, or + hosted offering; +- using a RememberStack logo, or a modified version of one, to brand a product or + service; +- implying that a fork, event, service, certification, or organization is official, + sponsored, or endorsed; or +- using a Mark on merchandise or other goods. + +A modified distribution may describe itself as based on RememberStack, but it must use +a distinct primary name and must not imply that WriteIt.ai created, supports, or +warrants the modifications. + +## General conditions + +Do not use the Marks in a misleading or confusing way, combine them with another name +so that affiliation is implied, or register confusingly similar marks. Any goodwill +from permitted use of the Marks belongs to WriteIt.ai. We may ask You to correct a use +that creates confusion. + +For permission or questions, contact `info@writeit.ai`. diff --git a/decisions.md b/decisions.md index 0b017c58..f29df0b9 100644 --- a/decisions.md +++ b/decisions.md @@ -1893,9 +1893,9 @@ creation and `NOTIFY` in one transaction; the delivery port never creates the ro > claim: it closes the roadmap stack-conventions gate and records WP-0.1 done. It does **not** > claim that D61 ports, the two delivery shells, the intended hexagonal package directories, > or import-linter contracts are implemented; those remain the planned -> [WP-0.4](plan/plans/phase-0-foundations.md). D76 later closed the mechanical release rename; -> attorney clearance and the bounded CLA remain open in -> [`questions.md` §1 item 11a](questions.md#1-open-decisions-undecided--answers-shape-the-design). +> [WP-0.4](plan/plans/phase-0-foundations.md). D76 later closed the mechanical release rename, +> and D77 closed the remaining owner governance gate through explicit risk acceptance and the +> repository-native bounded CLA. ## D63. The embedding model is port configuration; default `qwen3-embedding-8b` via OpenRouter — the E1 branch resolves to conventional + prefix @@ -2580,5 +2580,51 @@ also rejected: the verb-shaped `remember` command is clearer and no compatibilit targets. `remember.dev` is the canonical URL in website metadata and deployment documentation; alternate website hosts redirect there. The repository rename is complete. Domain/DNS setup, PyPI Trusted Publisher, and public GHCR visibility are account-level release -steps. The bounded CLA and focused legal clearance remain the only owner-side gates before public -release. +steps. The former legal-clearance and CLA gates are resolved by D77. + +## D77. Public release proceeds with an in-repository, self-hosting-bounded CLA + +**Decision.** The owner accepts the documented naming risk around Recallstack and Remembra and +chooses to release RememberStack without making focused attorney clearance a blocking gate. This +is a risk acceptance, not a finding of trademark availability or legal clearance. + +Before the first outside contribution, the repository enforces the RememberStack Contributor +License Agreement v1.0. Contributors retain their copyright. They grant WriteIt.ai s.r.o. the +copyright and patent rights needed to maintain, distribute, and relicense their contributions, but +the outbound grant is bounded: every future license must keep the corresponding source available +without a license fee and permit personal, research, nonprofit, and internal commercial +self-hosting without seat, instance, data-volume, or duration limits. A future license may restrict +offering RememberStack as a hosted or managed service to third parties. Apache-2.0 remains the +launch license, and versions already published under it stay Apache-2.0. + +Acceptance is deliberately repository-native. Each human-authored pull request contains an exact +versioned assent checkbox, and a metadata-only `pull_request_target` workflow fails the `CLA` +status unless it is checked. The workflow never checks out or executes pull-request code. +Agreement revisions are versioned, require fresh assent, and do not retroactively enlarge an +earlier grant. Known dependency/automation bots are exempt because they cannot assent; maintainers +remain responsible for the provenance of bot-authored changes. + +The repository also ships a narrow trademark policy. Copyright permissions remain broad: +truthful references, interoperability identifiers, unmodified redistribution, and clearly +distinguished "based on RememberStack" forks need no permission. The policy reserves product, +service, package, domain, logo, and endorsement uses that could imply an official source. It does +not claim that the marks are registered. + +**Context.** D60's governance analysis rejected a plain DCO because it would not preserve the +option to adopt a source-available license if a competing hosted offering becomes material. An +unbounded CLA would solve that business problem by creating a larger contributor-trust problem. +The bounded grant makes the intended trade explicit. It is adapted from the Harmony Contributor +Agreement Template rather than invented from a blank page. + +The owner chose not to add a hosted CLA service, OAuth application, or separate signatory +database. GitHub's authenticated identity, pull-request body, edit history, and required status +form the acceptance record. This is the smallest mechanism that enforces the project decision +inside the public repository. Legal review remains advisable, particularly before an actual +relicense, but is no longer a release gate. + +**Consequences.** `CLA.md`, `TRADEMARKS.md`, `CONTRIBUTING.md`, the pull-request template, and the +`CLA` workflow ship together. The `CLA` status becomes a required `main` check with administrator +enforcement after the workflow lands. The PyPI pending publisher, matching protected GitHub +environment, and protected `v*` tag ruleset are already configured. The first GHCR push creates +the container package; making that package public is the only post-publish owner action. WP-7.6 +may proceed to its first tagged artifact proof after CLA activation. diff --git a/plan/designs/packaging_distribution_design.md b/plan/designs/packaging_distribution_design.md index 2b963405..76cc30af 100644 --- a/plan/designs/packaging_distribution_design.md +++ b/plan/designs/packaging_distribution_design.md @@ -275,7 +275,7 @@ must be rejected by the operator's transfer verification. ## References -Decisions: **D62** (this design), D7, D12, D48–D56, D60–D61 (`decisions.md`). Cloud-side +Decisions: **D62** (this design), D7, D12, D48–D56, D60–D61, D76–D77 (`decisions.md`). Cloud-side analyses: `ultimate-memory-cloud/analysis/oss_cloud_split/` (synthesis + licensing/naming). Plans: `plan/plans/roadmap.md` §3 (stack), phases 0/5/7 (the WPs realizing this design). -Open governance items (name, CLA): `questions.md` §11a. +Resolved governance record (name, bounded CLA): `questions.md` §11a. diff --git a/plan/plans/phase-7-scale-ops.md b/plan/plans/phase-7-scale-ops.md index 23850408..fe389cd5 100644 --- a/plan/plans/phase-7-scale-ops.md +++ b/plan/plans/phase-7-scale-ops.md @@ -19,8 +19,9 @@ Postgres state, narrow ports, typed settings, and CLI/admin surfaces along one s self-host and reference adapters. **Entry gates:** none. Work-package-local gates remain explicit: #24 is resolved by D74 before -WP-7.5 implementation. WP-7.6 engineering is implemented; its first public tag still waits for -focused name clearance, the bounded CLA, and account-level registry setup. +WP-7.5 implementation. WP-7.6 engineering and account-level registry setup are complete. D77 +records the owner's naming-risk acceptance and the bounded CLA; activating its required `CLA` +status remains before the first public tag and artifact proof. **Exit criteria:** fixed synthetic scale profiles exercise the D23 shapes and portable batching; a fixture budget parks and later resumes work without loss; telemetry/admin surfaces expose pipeline and DLQ state; rebuild and forget drills pass; S55 is green across active serving stores @@ -34,7 +35,7 @@ the operator-driven portable restore drill is green without a library transport | WP-7.3 | Cost metering + configurable budget enforcement | orchestration §4; schema §2 `cost_ledger` | WP-7.1 | enforcement + admin inspection | explicit fixture ceiling parks and resumes an over-budget lane; attribution is visible | done | | WP-7.4 | Operational correctness surfaces + drills: typed telemetry, pipeline/DLQ inspection and replay, P2/P3 rebuild, currency-ledger audit | orchestration §6–7; D7, D60–D61 | WP-7.1 | telemetry/admin surfaces + deterministic drills | failures remain visible and drills pass without a dashboard or hosted control plane | done | | WP-7.5 | **Hard-delete end-to-end**: purge active P1/P2/P3/K surfaces and prevent restore resurrection through the D74 portable manifest/adapter contract | hard-forget design; lifecycle §8; k_layers §10; S55 | D74 (gate #24 resolved) | forget pipeline | **S55 CI gate ON and green** across library-controlled surfaces + restore canary | done | -| WP-7.6 | **Release engineering**: semver across PyPI + the shared GHCR image + pinned compose; migrations-before-workers upgrade drill; quickstart cold-start release gate | packaging §1, §5–6; D62, D76 | WP-7.1, owner release gates | release pipeline | tagged release produces all artifacts; upgrade drill green; quickstart under target | implemented (public tag waits on owner gates) | +| WP-7.6 | **Release engineering**: semver across PyPI + the shared GHCR image + pinned compose; migrations-before-workers upgrade drill; quickstart cold-start release gate | packaging §1, §5–6; D62, D76–D77 | WP-7.1, owner release gates | release pipeline | tagged release produces all artifacts; upgrade drill green; quickstart under target | implemented (CLA activation, then first-tag artifact proof, remain) | | WP-7.7 | **Portable state + restore round-trip**: define the authoritative store set and fail-closed restore order; operators move bytes with native tools and projections rebuild normally | packaging §6; D7, D60, D74–D75 | WP-7.1, WP-7.5 | portability contract + deterministic drill | real PostgreSQL restore plus whole/independent external-store canaries → no resurrection + control green | done | ## WP-7.1 implementation @@ -163,9 +164,11 @@ start. The final checks require the head migration, preserved deployment, all th a reachable health endpoint. [`RELEASING.md`](../../RELEASING.md) records the deliberately manual owner steps and the clean -verification commands. The repository rename is complete. Focused name clearance, the bounded -CLA, PyPI environment/pending publisher, and first-package GHCR visibility remain public-release -gates rather than OSS runtime features. +verification commands. The repository rename, D77 risk acceptance, PyPI environment/pending +publisher, and release-tag protection are complete. The bounded CLA lands before its emitted check +is made required on `main`; only then does the first tag supply the artifact proof. Making the newly +created GHCR package public remains the one post-publish owner step rather than an OSS runtime +feature. ## WP-7.7 implementation diff --git a/plan/plans/roadmap.md b/plan/plans/roadmap.md index e3197de3..542dafff 100644 --- a/plan/plans/roadmap.md +++ b/plan/plans/roadmap.md @@ -115,7 +115,7 @@ as usual): | Gate | Blocks | What must be decided | |---|---|---| | stack conventions (§3; **resolved 2026-07-17**) | Phase 0 WP-0.1 | Closed by the merged scaffold in [PR #39](https://github.com/writeitai/remember-stack/pull/39) and configuration convention in [PR #41](https://github.com/writeitai/remember-stack/pull/41); §3 maps every former slot to its exact repository evidence. | -| public-release governance (`questions.md` §11a; D76) | first public tag, first outside PR | focused attorney clearance before release; bounded CLA before external contributions | +| public-release governance (`questions.md` §11a; **decided 2026-07-23 → D77; activation pending**) | first public tag, first outside PR | Owner accepted the documented naming risk and selected the repository-native, self-hosting-bounded CLA plus narrow trademark policy; close the implementation gate by making the emitted `CLA` status required on `main`. | | #3 embedding model + dimension (**resolved** → D63) | Phase 1 entry | closed: `qwen3-embedding-8b` port default; conventional + prefix binds (e1 §5); stored dimension remains a D22 measurement | | #4 LLM per stage (**extractor seat resolved** → D70) | Phase 2 (adjudicators), Phase 6 (K writers) | extraction default `gpt-5.6-luna` closed Phase 1's gate; remaining seats inherit the port-default principle, gated by their phases' measurements (D53 family split holds) | | #7 PageIndex hosted vs self-hosted (**resolved** → D71: neither — a port-configured LLM seat + deterministic snap) | Phase 3 (full structure route) | closed: the snap guards any seat's output; no external tool dependency | diff --git a/questions.md b/questions.md index a66cbae7..8d929f6b 100644 --- a/questions.md +++ b/questions.md @@ -65,18 +65,20 @@ Keep this current: when something here is decided, move it to a decision and pru 11. ~~**Backfill / reprocessing orchestration design**~~ **RESOLVED (D52/D67; `orchestration_design.md` §2–§4).** Phase 7 WP-7.1 implements the existing version-filtered seeder, separate lane, throttling, resumability, and rollback/replay semantics. -11a. **OSS governance & release readiness (D60/D61).** Must be settled before outside - contributions / public release. Conclusions so far (2026-07-08 comparables + name check; full +11a. **OSS governance & release readiness (D60/D61) — DECIDED (D77, 2026-07-23); + CLA activation pending.** Conclusions (2026-07-08 comparables + 2026-07-23 owner resolution; full detail in the cloud repo's split analysis, `04_licensing_naming_findings.md`): - **License: stay Apache-2.0** (already shipped). Verified comparables: Sentry FSL-1.1-Apache-2.0 (tightened only after a decade of dominance), E2B Apache-2.0, Hermes agent (Nous Research) MIT — agent-era infrastructure launches permissive; adoption is the existential game. Apache over MIT for the explicit patent grant. FSL stays a *documented trigger* (a competing hosted offering at meaningful scale), never a launch choice. - - **CLA with a *bounded* relicense grant** (e.g. "only to licenses that keep self-hosting free") - rather than plain DCO — preserves the FSL escape hatch (Apache versions already published stay - Apache forever) while blunting the usual contributor objection. Must exist before the first - outside PR. + - **The bounded CLA is specified by D77** rather than a plain DCO. Contributors retain + ownership; the grant preserves a hosted-service-protective license option only when source + remains available and self-hosting remains free. `CLA.md` plus versioned pull-request assent + land first; this gate closes when the emitted `CLA` status is required on `main`. + `TRADEMARKS.md` separately allows truthful reference, interoperability, unmodified releases, + and clearly distinguished forks while reserving confusing official-product uses. - ~~"Ultimate Memory" is a working title — a rename gates public release~~ **NAME DECIDED (D76, 2026-07-23): product `RememberStack`, canonical home `remember.dev`, attribution “RememberStack by WriteIt.ai.”** The release identifiers are repository @@ -84,16 +86,14 @@ Keep this current: when something here is decided, move it to a decision and pru `ghcr.io/writeitai/remember-stack`, and configuration prefix `REMEMBERSTACK_*`. The domain remains the canonical public address; the full product mark appears in product prose and metadata. The pre-release working identifiers received one clean rename with no compatibility - aliases. **Still gating public release:** focused attorney clearance against the close - in-category Recallstack and Remembra names, plus the bounded CLA before outside - contributions. Preliminary availability research is not legal clearance. + aliases. Preliminary availability research is not legal clearance; under D77 the owner + explicitly accepts that risk and removes focused attorney clearance as a release gate. - ~~The packaging/distribution design~~ **RESOLVED (D62)** — `plan/designs/packaging_distribution_design.md`: the three artifacts, the client surface (lineage-aware ingest; connector management vs execution), delivery-only task execution over `processing_state` with the two shells + janitor, the enforced hexagonal layout, - compose profiles, release/upgrade/portable-restore policy. D76 supplied the exact targets - and the mechanical rename is complete; focused clearance and the **CLA** remain owner-side - gates above. + compose profiles, release/upgrade/portable-restore policy. D76 supplied the exact targets, + the mechanical rename is complete, and D77 decides the governance policy pending activation. - ~~Stack-convention slots (roadmap §3).~~ **RESOLVED (2026-07-17; `PLAN-RECONCILIATION-WP-0.1-STACK-CONVENTIONS` / WP-0.1)** — [PR #39](https://github.com/writeitai/remember-stack/pull/39) merged `uv`/Hatchling, @@ -101,7 +101,7 @@ Keep this current: when something here is decided, move it to a decision and pru [PR #41](https://github.com/writeitai/remember-stack/pull/41) merged the typed pydantic-settings/secret convention and direct-environment-access lint guard. The roadmap now links each choice to the exact repository evidence. The release rename is - now complete; attorney clearance and the bounded CLA remain open above. + complete; the D77 `CLA` required-check activation is the remaining governance step. ## 2. Open objections (unresolved critique — see `objections.md`) diff --git a/website/src/app/docs/deployment/page.mdx b/website/src/app/docs/deployment/page.mdx index 84e4feb6..afe234aa 100644 --- a/website/src/app/docs/deployment/page.mdx +++ b/website/src/app/docs/deployment/page.mdx @@ -15,8 +15,10 @@ deployment, and seeds the canonical retrieval recipes. This is a pre-release infrastructure proof. It processes a Markdown upload through conversion and deterministic structure, then leaves its chunk work pending. Later pipeline workers are not yet wired into this quickstart. The -release workflow and tag-pinned Compose contract exist, but no public PyPI or -GHCR artifact has been released while the owner-side release gates remain open. +release workflow and tag-pinned Compose contract exist and trusted publishing is +configured. The bounded contributor-agreement workflow still needs activation as +a required `main` check before the first public tag is created, so no public PyPI +or GHCR artifact exists yet. The RememberStack, `rememberstack`, and `remember` names used here are final. Do not expose this stack to untrusted traffic. diff --git a/website/src/app/docs/project-status/page.mdx b/website/src/app/docs/project-status/page.mdx index 9ea251d2..c2bc4ebf 100644 --- a/website/src/app/docs/project-status/page.mdx +++ b/website/src/app/docs/project-status/page.mdx @@ -22,7 +22,7 @@ RememberStack is being built **design-first**: the complete system — requireme - **Phase 5, complete** — retrieval complete. The full zero-LLM primitive set is implemented (`fuse`, `rerank`, `transcript`, `delta`, `pages_about`, enumerated `aggregate`, and a streaming batch `scan`, alongside resolve/lookup/search/graph); recipes are registry rows whose declared grain is enforced mechanically; and the self-accounting envelope surfaces contradictions, withdrawn support, mixed-grain parts, identity regime, belief horizons, freshness, and typed negatives. API, CLI, and MCP all render the same deployment registry. The consumption skill is guarded by the repeatable S58 cold-agent eval, while the retrieval spike battery records filtered Lance search at 10 million rows and graph pagination at a 100,000-edge hub. The client-first `rememberstack` base wheel contains the typed SDK, remote `remember` CLI and MCP, lineage-aware E0 ingest, and typed remote connector-management commands plus their deployment composition port, without server dependencies; `[server]`, `[connectors-watched-directory]`, and `[k]` name the heavier install surfaces. - **Phase 6, complete** — Plane K now includes the deterministic control plane and crash-safe single-committer driver, exact rule routing and staleness, deterministic fact-sheet and agent-written prose bands, planner/reflection decisions with quarantine and adoption, and authored-page frontmatter, citations, watches, review flags, and debounced workflow dispatch. D73 removed the proposed K3 tier: personal or organizational principles are authored K2 content, supported by compiled scope pages and never machine-promoted or rewritten. - **Phase 3, complete** — the evidence lifecycle: documents that change. Watched sources poll as recorded sync cycles (a local-directory watcher ships; revision and content no-ops, debounce, source-deletion detection); an edited document becomes a new version of its lineage and the full structure route (an LLM-proposed section tree normalized by a deterministic snap) re-reads it; unchanged chunks reuse their prior claims, prefixes, and vectors so cost is proportional to the edit (measured hit rate 0.79 on the spike corpus); reconciliation transitions testimony currency on an append-only ledger, recounts evidence by distinct current lineages, closes solely-supported facts when the source withdrew them (at the sync-cycle barrier, so a moved section is a support swap — never a retract flicker) and flags them for review when only the toolchain changed; deletion removes a document's contribution uniformly while keeping its claims as history; and a standing `lifecycle` eval suite guards the cache/ledger/count invariants with planted regression canaries. Those lifecycle events now feed the graph, corpus filesystem, and Plane-K control plane described above. -- **Phase 7, in progress** — operational correctness now includes resumable initial-load and version-bump backfill on the same work ledger, a reproducible PostgreSQL scale battery for the designed partitions, indexes, hubs, and batching invariants, and optional per-deployment/stage/lane cost ceilings. Budget exhaustion parks healthy work durably without consuming an attempt; the local CLI reports current spend, remaining budget, tier attribution, and parked work from the same authoritative rows. Typed worker telemetry preserves complete exception chains, while bounded CLI inspection exposes pipeline/DLQ state, poison targets, P2/P3 pointers, and currency-ledger drift; an explicit one-row replay grants only additional attempts, and rebuild drills call the production P2/P3 builders. Hard-forget now purges every active library-controlled surface and replays a separately durable, content-free manifest before serving after a restore. Portability is deliberately smaller than a backup product: operators move PostgreSQL, objects, and Git with native tools; the library defines the fail-closed restore order and rebuilds P1/P2/P3. A fresh-deployment Compose skeleton now wires PostgreSQL, MinIO, the API, and the conversion/structure workers through the real profile. Release engineering enforces one semantic version across PyPI, the shared API/worker GHCR image, and Compose; CI measures cold start and drills a schema downgrade followed by migrations-before-process-restart. The pipeline is ready, but no public artifact exists until the owner-side legal, CLA, repository, and registry gates are completed. Timings remain measurements rather than hosted SLAs, and no export/import CLI, dashboard, billing policy, HA topology, backup scheduler, or control plane enters the library. +- **Phase 7, implemented; governance activation and first tag pending** — operational correctness now includes resumable initial-load and version-bump backfill on the same work ledger, a reproducible PostgreSQL scale battery for the designed partitions, indexes, hubs, and batching invariants, and optional per-deployment/stage/lane cost ceilings. Budget exhaustion parks healthy work durably without consuming an attempt; the local CLI reports current spend, remaining budget, tier attribution, and parked work from the same authoritative rows. Typed worker telemetry preserves complete exception chains, while bounded CLI inspection exposes pipeline/DLQ state, poison targets, P2/P3 pointers, and currency-ledger drift; an explicit one-row replay grants only additional attempts, and rebuild drills call the production P2/P3 builders. Hard-forget now purges every active library-controlled surface and replays a separately durable, content-free manifest before serving after a restore. Portability is deliberately smaller than a backup product: operators move PostgreSQL, objects, and Git with native tools; the library defines the fail-closed restore order and rebuilds P1/P2/P3. A fresh-deployment Compose skeleton now wires PostgreSQL, MinIO, the API, and the conversion/structure workers through the real profile. Release engineering enforces one semantic version across PyPI, the shared API/worker GHCR image, and Compose; CI measures cold start and drills a schema downgrade followed by migrations-before-process-restart. Trusted publishing and protected release tags are configured; the repository-native bounded CLA lands before its emitted status becomes required on `main`, then the first public tag remains the artifact proof. Timings remain measurements rather than hosted SLAs, and no export/import CLI, dashboard, billing policy, HA topology, backup scheduler, or control plane enters the library. ## The build order