access_grant 1.0.0

data/docs/superpowers/plans/2026-09-08-gem-release.md

@@ -0,0 +1,367 @@
+# Gem Release Automation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-ruby:subagent-driven-development (recommended) or superpowers-ruby:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a manually triggered GitHub Actions release that publishes `access_grant` 1.0.0 to RubyGems via Trusted Publishing, creates a GitHub Release, and shows version/CI/license badges on the README.
+
+**Architecture:** Hybrid release — humans bump `version.rb` + `CHANGELOG.md` on `main`; `workflow_dispatch` with a `version` input guards those values, then `rubygems/release-gem` (OIDC) tags and pushes the gem; a follow-up step opens the GitHub Release from the matching CHANGELOG section.
+
+**Tech Stack:** GitHub Actions, `rubygems/release-gem@v1`, Bundler gem tasks, Keep a Changelog, shields.io / badge.fury badges.
+
+**Spec:** `docs/superpowers/specs/2026-09-08-gem-release-design.md`
+
+---
+
+## File map
+
+| File | Responsibility |
+|------|----------------|
+| `.github/workflows/release.yml` | Manual release: version guards, gem publish, GitHub Release |
+| `lib/access_grant/version.rb` | Canonical gem version (`1.0.0`) |
+| `CHANGELOG.md` | Keep a Changelog notes for `1.0.0` |
+| `README.md` | Badges + published-gem status wording |
+| `CONTRIBUTING.md` | Human release steps + Trusted Publisher setup |
+| `access_grant.gemspec` | Align `homepage` / metadata URIs with GitHub owner `SahSantoshh` if needed |
+
+---
+
+### Task 1: Bump version and CHANGELOG to 1.0.0
+
+**Files:**
+- Modify: `lib/access_grant/version.rb`
+- Modify: `CHANGELOG.md`
+
+- [ ] **Step 1: Set version constant to 1.0.0**
+
+Replace contents of `lib/access_grant/version.rb` with:
+
+```ruby
+# frozen_string_literal: true
+
+module AccessGrant
+  VERSION = "1.0.0"
+end
+```
+
+- [ ] **Step 2: Move Unreleased notes under `[1.0.0]`**
+
+Update `CHANGELOG.md` so that:
+
+1. `## [Unreleased]` remains, with no entries yet (empty section or just the heading).
+2. Current bullet list under `[Unreleased]` moves under `## [1.0.0] - 2026-09-08`.
+3. Keep the existing `## [0.1.0] - 2026-09-05` skeleton entry below.
+
+Expected shape:
+
+```markdown
+## [Unreleased]
+
+## [1.0.0] - 2026-09-08
+
+### Added
+
+- **Configuration** — …
+(…all former Unreleased Added bullets…)
+
+## [0.1.0] - 2026-09-05
+
+- Initial gem skeleton (pre-release, unpublished).
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add lib/access_grant/version.rb CHANGELOG.md
+git commit -m "$(cat <<'EOF'
+chore: bump version to 1.0.0
+
+Prepare the first public release notes and version constant for
+RubyGems / GitHub Release publishing.
+EOF
+)"
+```
+
+---
+
+### Task 2: Add release workflow
+
+**Files:**
+- Create: `.github/workflows/release.yml`
+
+- [ ] **Step 1: Create the workflow file**
+
+Create `.github/workflows/release.yml` with exactly this content (no GitHub Environment block — Trusted Publisher environment must stay blank to match):
+
+```yaml
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Gem version to release (must match AccessGrant::VERSION)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Publish gem ${{ inputs.version }}
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.1"
+          bundler-cache: true
+
+      - name: Assert version matches
+        env:
+          EXPECTED_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          ACTUAL="$(ruby -r./lib/access_grant/version -e 'print AccessGrant::VERSION')"
+          if [ "$ACTUAL" != "$EXPECTED_VERSION" ]; then
+            echo "::error::AccessGrant::VERSION ($ACTUAL) != workflow input ($EXPECTED_VERSION)"
+            exit 1
+          fi
+          if ! grep -qE "^## \[${EXPECTED_VERSION}\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md missing heading ## [${EXPECTED_VERSION}]"
+            exit 1
+          fi
+          echo "Releasing access_grant ${EXPECTED_VERSION}"
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1
+
+      - name: Extract changelog notes
+        id: notes
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          NOTES_FILE="${RUNNER_TEMP}/release_notes.md"
+          awk -v ver="$VERSION" '
+            $0 ~ "^## \\[" ver "\\]" {capture=1; next}
+            /^## \[/ {if (capture) exit}
+            capture {print}
+          ' CHANGELOG.md > "$NOTES_FILE"
+          if [ ! -s "$NOTES_FILE" ]; then
+            echo "::error::No CHANGELOG body found for ${VERSION}"
+            exit 1
+          fi
+          {
+            echo "path=${NOTES_FILE}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ inputs.version }}
+          name: v${{ inputs.version }}
+          body_path: ${{ steps.notes.outputs.path }}
+          fail_on_unmatched_files: true
+```
+
+Notes for implementers:
+
+- `rubygems/release-gem` runs Bundler’s `rake release` (build, tag `vX.Y.Z`, push tag, `gem push` via OIDC).
+- Do **not** add `environment: release` unless RubyGems Trusted Publisher is also configured with that environment name.
+- Trusted Publisher on RubyGems must use workflow filename `release.yml` and repository `SahSantoshh/access_grant`.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .github/workflows/release.yml
+git commit -m "$(cat <<'EOF'
+ci: add manual RubyGems release workflow
+
+Add workflow_dispatch release with version guards, Trusted Publishing
+via rubygems/release-gem, and GitHub Release notes from CHANGELOG.
+EOF
+)"
+```
+
+---
+
+### Task 3: README badges and status wording
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Add badges and update status blurb**
+
+At the top of `README.md`, immediately after `# AccessGrant`, insert:
+
+```markdown
+[![Gem Version](https://badge.fury.io/rb/access_grant.svg)](https://rubygems.org/gems/access_grant)
+[![CI](https://github.com/SahSantoshh/access_grant/actions/workflows/ci.yml/badge.svg)](https://github.com/SahSantoshh/access_grant/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+```
+
+Replace the status blockquote:
+
+```markdown
+> **Status: v1 implementation.** Full design:
+> [`docs/architecture.md`](docs/architecture.md),
+> [`docs/proposal.md`](docs/proposal.md).
+```
+
+with:
+
+```markdown
+> **Status:** v1.0 published on [RubyGems](https://rubygems.org/gems/access_grant).
+> Design: [`docs/architecture.md`](docs/architecture.md),
+> [`docs/proposal.md`](docs/proposal.md).
+```
+
+Preserve the rest of the README unchanged unless badges were already partially added — do not duplicate badge lines.
+
+- [ ] **Step 2: Align gemspec homepage with GitHub owner (if mismatched)**
+
+If `access_grant.gemspec` still points at `https://github.com/santoshsah/access_grant`, update `spec.homepage` (and derived metadata URIs) to `https://github.com/SahSantoshh/access_grant` so RubyGems links match the real repo.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md access_grant.gemspec
+git commit -m "$(cat <<'EOF'
+docs: add release badges and published status
+
+Surface RubyGems/CI/license badges and point homepage metadata at the
+canonical GitHub repository.
+EOF
+)"
+```
+
+---
+
+### Task 4: Update CONTRIBUTING release docs
+
+**Files:**
+- Modify: `CONTRIBUTING.md` (section `## Versioning & releases`)
+
+- [ ] **Step 1: Replace the release section**
+
+Replace the entire `## Versioning & releases` section with:
+
+```markdown
+## Versioning & releases
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+### Cut a release
+
+1. Open a PR on `main` that:
+   - Bumps `AccessGrant::VERSION` in `lib/access_grant/version.rb`
+   - Moves `[Unreleased]` entries in `CHANGELOG.md` under
+     `## [X.Y.Z] - YYYY-MM-DD` and leaves a fresh empty `[Unreleased]`
+   - Uses commit message `chore: release vX.Y.Z`
+2. Merge the PR and wait for CI on `main` to pass.
+3. In GitHub Actions, run the **Release** workflow on `main` with input
+   `version` set to `X.Y.Z` (must match `AccessGrant::VERSION`).
+4. The workflow:
+   - Fails fast if the version or CHANGELOG heading does not match
+   - Publishes the gem to RubyGems.org via Trusted Publishing (OIDC)
+   - Creates git tag `vX.Y.Z` and a GitHub Release from the CHANGELOG section
+
+Do **not** run `bundle exec rake release` locally for production publishes;
+Actions owns tagging and `gem push`.
+
+### One-time RubyGems setup
+
+1. Create a RubyGems.org account and enable MFA.
+2. Configure a [Trusted Publisher](https://guides.rubygems.org/trusted-publishing/)
+   for gem `access_grant`:
+   - Repository owner: `SahSantoshh`
+   - Repository name: `access_grant`
+   - Workflow filename: `release.yml`
+   - Environment: leave blank (must match the workflow — no `environment:` key)
+3. For the first publish, use RubyGems’ pending trusted-publisher flow if the
+   gem name is not on the index yet.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add CONTRIBUTING.md
+git commit -m "$(cat <<'EOF'
+docs: document hybrid Actions release process
+
+Replace local rake release instructions with the manual workflow_dispatch
+flow and Trusted Publisher setup notes.
+EOF
+)"
+```
+
+---
+
+### Task 5: Verify locally (no publish)
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Confirm version loads**
+
+Run:
+
+```bash
+ruby -r./lib/access_grant/version -e 'puts AccessGrant::VERSION'
+```
+
+Expected: `1.0.0`
+
+- [ ] **Step 2: Confirm CHANGELOG heading exists**
+
+Run:
+
+```bash
+grep -E '^## \[1\.0\.0\]' CHANGELOG.md
+```
+
+Expected: a line starting with `## [1.0.0]`
+
+- [ ] **Step 3: Confirm workflow file is valid YAML-ish**
+
+Run:
+
+```bash
+ruby -ryaml -e 'YAML.load_file(".github/workflows/release.yml"); puts "ok"'
+```
+
+Expected: `ok`
+
+- [ ] **Step 4: Do not publish from the agent**
+
+Publishing requires the maintainer to configure Trusted Publishing and click **Run workflow**. After merge to `main`, the human runs Release with `version: 1.0.0`.
+
+---
+
+## Spec coverage checklist
+
+| Spec requirement | Task |
+|------------------|------|
+| Manual `workflow_dispatch` + version input | Task 2 |
+| Hybrid version bump + CHANGELOG 1.0.0 | Task 1 |
+| Trusted Publishing / `rubygems/release-gem` | Task 2 |
+| GitHub Release from CHANGELOG | Task 2 |
+| README badges | Task 3 |
+| CONTRIBUTING update | Task 4 |
+| No CI matrix in release job | Task 2 (omitted by design) |
+| No yank / no changelog automation | Out of scope (omitted) |
+
+## Handoff note for humans
+
+After this lands on `main`: configure Trusted Publisher on RubyGems, then run **Actions → Release → Run workflow** with `version: 1.0.0`.

data/docs/superpowers/specs/2026-09-05-owner-role-design.md

@@ -0,0 +1,271 @@
+# Owner role for tenant creator
+
+> Status: **design finalized** (docs only; not yet implemented)
+> Date: 2026-09-05; updated 2026-09-07
+
+Privileged Owner role with explicit host-side assignment. The gem
+provides the Owner API and rules; the host app decides who becomes
+Owner and when (for example after creating an organization).
+
+## Responsibility split
+
+**Gem owns**
+
+- Privileged Owner behavior via `config.owner_role`
+  (`:protected` | `:bypass` | `:both` | `:none`)
+- `grant_owner!(user)` / `revoke_owner!(user)` on the tenant
+  (multi-tenant) or `AccessGrant.grant_owner!` /
+  `AccessGrant.revoke_owner!` (single-tenant)
+- Enforce “at least one Owner” when revoking, once an Owner exists
+- Seed/protect Owner rows and re-attach catalog keys on sync for
+  `:protected` / `:both`
+- Generators, DSL, `permitted?`, and optional controller authorize hook
+  (no Policy classes)
+
+**Host app owns**
+
+- Who the org creator is
+- When to call `grant_owner!` (controller, service, callback, seeds)
+- Single-tenant first Owner (seeds or console)
+
+The gem does **not** auto-detect a creator for `grant_owner!`. The authorize
+hook defaults to controller methods `current_user` / `current_tenant` only
+at the edge (host implements `current_tenant` when multi-tenant).
+
+```ruby
+# Host app — project responsibility
+org = Organization.create!(name: "Acme")
+org.grant_owner!(current_user)
+```
+
+## Data model
+
+**Phase 1 — `rails g access_grant:install`**
+
+Creates core tables only (no tenant or user assumptions):
+
+- `permissions` — catalog keys
+- `roles` — `name` only (no tenant column yet)
+- `role_permissions` — role ↔ permission
+
+**Phase 2 — `rails g access_grant:setup`**
+
+Accepts flags (non-interactive) or asks interactively when omitted:
+
+```
+rails g access_grant:setup \
+  --multi-tenant \
+  --tenant=Organization \
+  --user=User \
+  --owner-role=protected
+```
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `--multi-tenant` / `--single-tenant` | Scope mode | asked if omitted |
+| `--tenant=Organization` | Tenant class (multi-tenant only) | `Organization` |
+| `--user=User` | User class | `User` |
+| `--owner-role=protected` | Owner mechanism | `protected` |
+
+Writes:
+
+- Migrations for the tenant FK on `roles` (multi-tenant only) and the
+  user↔role join (`user_roles`, `account_roles`, …)
+- `config/initializers/access_grant.rb` with the chosen classes and
+  Owner settings
+- **Patches host models:** inserts `access_grant :tenant` into the
+  tenant model file and `access_grant :user` into the user model
+  file (skips if already present; fails clearly if the model file
+  cannot be found)
+
+```
+Organization ──< Role >── role_permissions ── Permission
+                 │
+                 └──< user_roles >── User
+```
+
+No Membership model. Membership remains a host concern if the app
+needs it; AccessGrant attaches roles to the configured user.
+
+## DSL
+
+```ruby
+class Organization < ApplicationRecord
+  access_grant :tenant
+end
+
+class User < ApplicationRecord
+  access_grant :user
+end
+```
+
+Replaces the earlier proposed `acts_as_permission_tenant` /
+`acts_as_permissible`. One method, two hats. The `setup` generator
+inserts these lines into the named model files; the host can still
+add or edit them by hand if needed.
+
+## Owner behavior
+
+### Config
+
+```ruby
+AccessGrant.configure do |config|
+  config.owner_role = :protected  # :protected | :bypass | :both | :none
+  config.owner_role_name = "Owner"
+end
+```
+
+Default mechanism is `:protected` when the host skips the setup
+question.
+
+### Assignment API
+
+```ruby
+# Multi-tenant
+org.grant_owner!(maya)
+org.revoke_owner!(maya)
+org.grant_owner!(jordan)  # multiple Owners allowed
+
+# Single-tenant
+AccessGrant.grant_owner!(maya)
+AccessGrant.revoke_owner!(maya)
+```
+
+`grant_owner!`:
+
+1. Finds or creates the Owner role for that scope
+2. Applies the configured mechanism (attach all catalog keys when
+   `:protected` or `:both`)
+3. Inserts the user↔role row
+
+Creating a tenant without calling `grant_owner!` is allowed. The gem
+does not enforce a first Owner on create. The “at least one Owner”
+rule applies only when **revoking**: you cannot go from one Owner to
+zero. Ops can still recover via `access_grant:grant_role`.
+
+If `owner_role` is `:none`, `grant_owner!` raises so the host notices
+Owner is turned off.
+
+### Mechanisms
+
+| `owner_role` | Role row | Permission rows | `permitted?` | Strip / delete Owner | Remove last Owner |
+|---|---|---|---|---|---|
+| `:none` | not seeded | — | normal join | n/a | n/a |
+| `:protected` | seeded | every catalog key; sync re-attaches | normal join | no | no |
+| `:bypass` | seeded | optional | short-circuit true if user has Owner | role assignable | no (still block last) |
+| `:both` | seeded | every catalog key + sync | short-circuit true | no | no |
+
+Plain-language examples:
+
+- **`:protected`** — Owner is a full keyring in the database. Maya
+  cannot uncheck permissions on Owner or delete the role. She can
+  make Jordan an Owner, then give up her own key.
+- **`:bypass`** — Having the Owner role name is enough for
+  `permitted?` to return true, even with empty permission rows.
+- **`:both`** — Full keyring and short-circuit.
+- **`:none`** — No special Owner; host builds roles only; lockout
+  rake task is the floor.
+
+### Catalog sync
+
+`access_grant:sync_permissions` upserts catalog keys. For
+`:protected` and `:both`, it also re-attaches every catalog
+permission to every Owner role in scope.
+
+## Permission checks
+
+```ruby
+# Multi-tenant — “Can Maya run invoices#index in Acme?”
+maya.permitted?("invoices.index", tenant: acme)
+
+# Single-tenant
+maya.permitted?("invoices.index")
+```
+
+Missing `tenant:` in multi-tenant mode **raises**. Unknown keys **raise**
+(including under Owner bypass). No gem-level memoization — see
+architecture resolved decisions.
+
+## Error cases
+
+- **Forgot first Owner** — Acme exists with zero Owners until the
+  host calls `grant_owner!` or ops runs the rake task. Allowed.
+- **Revoke last Owner** — fails with a clear error that the scope
+  must keep at least one Owner (`:protected`, `:bypass`, `:both`).
+- **Wrong tenant** — `maya.permitted?(:key, tenant: beta)` is false
+  if Maya only has roles on Acme.
+- **Owner off** — `grant_owner!` raises when `owner_role` is `:none`.
+
+## Lockout escape hatch
+
+Operational rake task remains for recovery (including zero-Owner
+scopes after a forgotten grant, or data repair):
+
+```
+bundle exec rake access_grant:grant_role[role_name,user_id]
+```
+
+Out of band only — not an ambient bypass in `permitted?` beyond the
+configured Owner mechanism.
+
+## Out of scope
+
+- Auto-granting Owner from `Current.user` or a creator association
+- Membership as the gem’s identity model
+- Fully tenant-less installs beyond single-tenant mode (roles with
+  no tenant column)
+- Engine implementation (this document is design only)
+
+## Decisions
+
+- **Owner is privileged (configurable floor).** Revises the earlier
+  “no unrevokable super-admin” product requirement. Rationale: orgs
+  need a floor so the creator cannot lock themselves out by editing
+  Owner’s permissions.
+- **Privilege mechanism is a host choice** — `:protected` (default),
+  `:bypass`, `:both`, or `:none`. Rationale: different hosts want
+  different floors; the gem should not hardcode one mechanism.
+- **Assignment is always explicit via `grant_owner!`.** The host
+  decides who the creator is and when to grant. Rationale: detecting
+  “who created the org” is project responsibility, not the gem’s.
+- **Creating a tenant without an Owner is allowed.** The gem does
+  not enforce first Owner on create. Rationale: follows from
+  host-owned assignment.
+- **Multiple Owners per scope are allowed.** Rationale: orgs have
+  more than one person who needs the floor.
+- **At least one Owner when revoking.** You cannot remove the last
+  Owner in a scope (when Owner is enabled). Rationale: the house
+  must keep a key-holder; the rake task is for ops, not accidental
+  zero Owners.
+- **No Membership in the gem.** User model is named at setup; join
+  is `#{user}_roles` / `user_roles`. Rationale: Membership is a host concern;
+  roles already belong to the tenant.
+- **`permitted?` takes an optional tenant** in multi-tenant mode.
+  Rationale: without Membership, tenant must be passed when a user
+  can belong to many orgs.
+- **Two-phase generator** — `access_grant:install` then
+  `access_grant:setup`. Setup accepts `--tenant`, `--user`,
+  `--multi-tenant` / `--single-tenant`, and `--owner-role` (or asks
+  interactively). Rationale: tenant wiring may not exist on day one;
+  flags keep CI/scripts non-interactive.
+- **Setup patches model files** with `access_grant :tenant` and
+  `access_grant :user`. Rationale: install should leave the host
+  wired without a manual model edit; skip if already present.
+- **DSL: `access_grant :tenant` / `access_grant :user`.** Replaces
+  `acts_as_permission_tenant` / `acts_as_permissible`. Rationale:
+  one method, two hats, simpler naming.
+- **Default `owner_role` is `:protected`.** Rationale: explicit
+  permission rows for everything, no `permitted?` short-circuit
+  unless the host opts in.
+- **No gem auto-detect of creator** (`Current.user`, creator
+  columns, etc.). Rationale: that responsibility stays on the
+  project side; the gem only exposes the API to configure and call.
+- **Permission keys are only `resource.action`** (strict regex; nothing
+  else stored). Keys are never taken from request params. Rationale:
+  predictable catalog, no injection-style free-text keys, harder to
+  misuse in authorize paths.
+- **Public-contract edge cases** (missing tenant, unknown keys,
+  freshness, Owner name reservation, catalog retirement, prefixed
+  tables) are resolved in architecture — see
+  [architecture.md](../../architecture.md#resolved-public-contract-decisions)
+  and the [usage scenarios](2026-09-07-usage-scenarios.md) inventory.