humanish 0.0.1 → 0.15.1

package/docs/release/open-source-readiness.md

@@ -0,0 +1,208 @@
+# Open-Source Release Readiness
+
+Date: 2026-06-02
+
+Status: HISTORICAL (banner added 2026-06-11). This audit declared the repo a
+public repository candidate after reviewed history cleanup; the repository
+has since gone public and the package has shipped releases past the `0.1.3`
+named below, so treat versions and one-time audit details here as a snapshot. The release gates and publish procedure remain the working
+reference. For the live goal state read
+[`docs/goals/current.md`](../goals/current.md). Actual
+`npm publish` remains a human release action and must not be run by an agent
+without explicit approval in the current context.
+
+Use [`docs/release/public-readiness-standard.md`](public-readiness-standard.md)
+as the public-cleanliness policy. The standard distinguishes real blockers such
+as secrets, PHI, private source, private screenshots, and raw credentials from
+acceptable public metadata such as maintainer-approved public commit email.
+
+## Package State
+
+- Package name: `humanish`
+- Version: `0.1.3`
+- Binary: `humanish`
+- License: MIT
+- Repository: `https://github.com/danielgwilson/humanish`
+- npm access: public via `publishConfig.access`
+- npm contents: compiled `dist`, public docs directories, including ramp and
+  current-goal docs, `skills/`,
+  `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and
+  `package.json`
+- GitHub Actions publish workflow: `.github/workflows/publish.yml`
+- optional live E2B peer: `@e2b/desktop`
+
+`prepack` runs the TypeScript build so a clean checkout can produce a usable
+tarball with `npm pack` or `npm publish`.
+
+## Skill State
+
+The installable agent skill lives at:
+
+```text
+skills/humanish/SKILL.md
+```
+
+This matches skills.sh discovery for `skills/<name>/SKILL.md`. The required
+frontmatter fields are present:
+
+```yaml
+name: humanish
+description: ...
+```
+
+Verification command:
+
+```bash
+DISABLE_TELEMETRY=1 npx skills add . --list
+```
+
+Expected install command after the repository is public:
+
+```bash
+npx skills add danielgwilson/humanish --skill humanish
+```
+
+## Public Boundary
+
+Release work must not include PII, PHI, secrets, keys, tokens, raw private
+transcripts, private screenshots, raw customer data, raw patient data, private
+source snippets, or generated run bundles.
+
+Allowed examples are synthetic or redacted only.
+
+## GitHub Visibility Gate
+
+The current tree and reachable Git history are the public surface being
+hardened here. The repository must not be made public until these checks pass
+from a fresh clone:
+
+- only the intended `main` branch is reachable;
+- no stale release tags point at pre-cleanup source;
+- history scans have no private upstream system names, absolute maintainer paths,
+  secret patterns, or generated runtime bundles;
+- reachable commit author and committer emails are GitHub noreply-style
+  addresses or explicitly approved public maintainer emails;
+- GitHub issues, PRs, labels, and project fields have been scanned or rewritten
+  for public-safe language.
+
+GitHub may still retain unreachable object caches or historical Actions logs
+internally. Treat those as residual platform-cache risk and delete old workflow
+runs before public launch if a stricter surface is required.
+
+History-check shape used during this audit:
+
+```bash
+git rev-list --all | xargs -n 32 git grep -n -I -i -e '<private-source-name>' -e '<absolute-local-path-marker>' -e '<workspace-path-marker>'
+git rev-list --all | xargs -n 32 git grep -n -I -E 'sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|BEGIN [A-Z ]*PRIVATE KEY|AIza[0-9A-Za-z_-]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}'
+```
+
+## Required Gates
+
+Run these before any public release candidate:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm public-surface:scan
+pnpm skill:check
+pnpm pack:dry-run
+git diff --check
+```
+
+`pnpm public-surface:scan` scans tracked files plus the npm dry-run payload,
+including built `dist/` output. It fails on common secret tokens, absolute local
+user paths, local workspace paths, unapproved durable commit email metadata,
+known private upstream system names, and binary public assets that are not
+explicitly allowlisted by SHA-256.
+
+## Tarball Inspection
+
+Use:
+
+```bash
+pnpm pack:dry-run
+```
+
+`pnpm pack:dry-run` delegates to `npm pack --dry-run` after `prepack` builds
+`dist`.
+
+The tarball must not include `.env*`, `.humanish/`, generated run bundles,
+private screenshots, raw transcripts, `.npmrc`, tests, fixtures, internal
+operations notes, local runtime caches, or private operator packets. Public
+`docs/ramp/`, `docs/goals/`, and repo-local `AGENTS.md` files are allowed when
+they are synthetic, durable, and public-safe. Public image assets must remain on
+the scanner allowlist and keep their approved checksum.
+
+## Publish Procedure
+
+Only after maintainer approval. Prefer the tag-gated GitHub Actions workflow
+over local publication:
+
+```bash
+pnpm release:check
+npm version patch --no-git-tag-version
+# Open and merge the release PR.
+git fetch origin main --tags
+git switch main
+git pull --ff-only origin main
+VERSION="$(node -p "require('./package.json').version")"
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
+```
+
+No agent should run `npm publish` locally without explicit human approval in the
+current thread. That approval must come from the maintainer responsible for the
+release.
+
+The release tag must point at a commit already reachable from `origin/main`.
+Tagging a local release commit before the release PR merges can publish a
+correct package from a commit that is not in main history. The publish workflow
+therefore fails closed unless the tag commit is an ancestor of `origin/main` and
+the tag name exactly matches `package.json`'s version.
+
+## Trusted Publishing Setup
+
+The npm package page exists. For the first tag after a repository rename, the
+order is load-bearing (the OIDC binding is exact owner/repo + workflow path):
+
+1. Rename the GitHub repository first.
+2. Configure/point the npm Trusted Publisher at the NEW repository name.
+3. Merge the release commit, then tag.
+
+A tag pushed before steps 1-2 fails auth (OIDC repository claim mismatch) or
+provenance validation (package.json repository.url vs actual workflow repo).
+
+Trusted Publishing should be configured for GitHub Actions before cutting the
+next tag:
+
+- provider: GitHub Actions
+- repository owner: `danielgwilson`
+- repository name: `humanish`
+- workflow filename: `publish.yml`
+- environment: blank
+- registry: npm public registry
+
+The workflow uses:
+
+- `permissions.id-token: write` for OIDC;
+- `permissions.contents: read`;
+- `actions/checkout@v6`;
+- `actions/setup-node@v6` with Node 24 and npm registry URL;
+- `npm publish --access public`;
+- no long-lived npm token secret.
+
+Future automated release flow after trusted publishing is configured:
+
+```bash
+pnpm release:check
+npm version patch --no-git-tag-version
+# Open and merge the release PR, then tag the pulled main commit.
+git fetch origin main --tags
+git switch main
+git pull --ff-only origin main
+VERSION="$(node -p "require('./package.json').version")"
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
+```
+
+The publish job is tag-gated and only publishes when running on a `v*` tag.

package/docs/release/public-readiness-standard.md

@@ -0,0 +1,205 @@
+# Public Readiness Standard
+
+Status: researched working standard for public repository and npm release hygiene.
+
+This document separates real public-release risk from preference cleanup. The
+goal is to keep `humanish` safe, useful, and professional without deleting the
+durable context future contributors and agents need.
+
+## Sources Reviewed
+
+- [GitHub Docs: Removing sensitive data from a repository](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
+- [GitHub Docs: Setting your commit email address](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address)
+- [GitHub Docs: About secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
+- [GitHub Docs: About push protection](https://docs.github.com/en/code-security/concepts/secret-security/about-push-protection)
+- [npm Docs: package.json files field](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#files)
+- [npm Docs: npm publish package contents](https://docs.npmjs.com/cli/v9/commands/npm-publish#files-included-in-package)
+- [npm Docs: Trusted publishing for npm packages](https://docs.npmjs.com/trusted-publishers/)
+- [OpenSSF Scorecard](https://scorecard.dev/)
+- [OpenSSF Source Code Management Platform Configuration Best Practices](https://best.openssf.org/SCM-BestPractices/)
+- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
+
+## Decision Model
+
+Use four categories.
+
+### 1. Public Blockers
+
+These must be removed from the current tree, package payload, generated docs,
+screenshots, logs, and reachable history before the repo is public.
+
+- Secrets: API keys, provider tokens, npm/GitHub tokens, private keys, cookies,
+  session URLs, database URLs with credentials, `.env` values, auth-bearing
+  request headers, and raw credential material.
+- PHI, patient data, customer data, private user identifiers, private emails,
+  phone numbers, addresses, account IDs, billing IDs, raw transcripts, and raw
+  screenshots from private systems.
+- Private source snippets, internal-only product names, private roadmaps,
+  incident details, or operational data that would expose a non-public system or
+  customer relationship.
+- Built package output, source maps, docs, fixtures, or image assets that contain
+  any of the above.
+
+If a real secret was exposed, revoke or rotate it first. GitHub explicitly warns
+that history rewriting has side effects and may not be warranted once the secret
+is revoked. Rewrite history only when sensitive data remains materially risky
+after revocation, or when privacy, legal, contractual, or proprietary-source
+obligations require removal.
+
+### 2. Release-Gate Hygiene
+
+These should fail CI or release checks until fixed, but they are not all reasons
+to rewrite history.
+
+- Package payload is not inspected with `npm pack --dry-run`.
+- Scanner only checks tracked source and misses built `dist`, source maps, docs
+  packaged by `files`, or generated assets.
+- Binary public assets are not approved by path and checksum.
+- Docs link to files that are not shipped or not reachable from the public repo.
+- Runtime artifacts are included: `.humanish/`, run bundles, transcripts,
+  disposable clones, `.firecrawl/`, `.e2b/`, logs, tarballs, caches.
+- GitHub Actions use broad default permissions where read-only is enough.
+- Publish workflow uses long-lived npm tokens when OIDC trusted publishing is
+  available.
+- Secret scanning, push protection, or equivalent local scanners are absent from
+  the operating checklist.
+
+### 3. Acceptable Public Metadata
+
+These are acceptable when intentional and public-safe. They should not trigger
+panic cleanup or history rewrite by default.
+
+- Maintainer name, GitHub username, public repo owner, public issue links, and
+  public repository URLs.
+- A maintainer-approved public commit email. GitHub allows either a noreply
+  address or any configured email for commits. Noreply is a privacy preference,
+  not a universal public-release requirement.
+- Env var names without values, such as `OPENAI_API_KEY` or `E2B_API_KEY`.
+- Synthetic personas, synthetic screenshots, synthetic app data, and redacted
+  proof examples.
+- Public-safe ramp, goal, architecture, and roadmap docs that help future
+  contributors continue the project.
+
+### 4. Professionalism Cleanup
+
+These do not usually justify history rewrite, but they matter for an open-source
+repo people will judge quickly.
+
+- Chat residue, private-process phrasing, or emotional notes that do not help a
+  public maintainer.
+- Overly specific local machine paths or private workspace names, even when not
+  security-sensitive.
+- Broken links, stale commands, claims of product proof where only contract proof
+  exists, and docs that depend on private chat memory.
+- Screenshots that are technically synthetic but look sloppy, confusing, or
+  embarrassing.
+
+Professionalism cleanup should preserve useful context. Deleting all ramp or
+goal docs is worse than rewriting them into a public-safe form.
+
+## Commit Email Policy
+
+Noreply commit emails are preferred for privacy and consistency.
+
+Allowed commit metadata:
+
+- GitHub noreply addresses.
+- `noreply@github.com` for GitHub-generated commits.
+- Explicitly approved public maintainer emails.
+
+Blocked commit metadata:
+
+- Unknown personal emails.
+- Contractor, employee, patient, customer, vendor, or private-domain emails that
+  are not intentionally public for this project.
+- Any email that appears in logs, transcripts, screenshots, or docs as private
+  user/customer data rather than maintainer metadata.
+
+Do not force-rewrite `main` solely because a known maintainer-approved public
+email appears in a commit. Document the approval and update the scanner
+allowlist instead.
+
+## NPM Package Surface
+
+The npm package is its own public surface. The release gate must inspect:
+
+- `npm pack --dry-run --json` output;
+- compiled `dist`;
+- source maps;
+- all files matched by `package.json.files`;
+- always-included files such as `package.json`, `README.md`, and `LICENSE`;
+- docs, skills, screenshots, and other assets shipped for npm-page display.
+
+The package should use the `files` field as an allowlist, but that is not enough.
+The scanner must union tracked source files with the actual npm dry-run payload.
+
+Public binary assets are allowed only when:
+
+- the asset is intentionally public;
+- the asset is synthetic or redacted;
+- the path is allowlisted;
+- the SHA-256 checksum is pinned in the scanner.
+
+## GitHub And Supply Chain Posture
+
+Minimum public-repo posture:
+
+- branch protection or rulesets for `main`;
+- required CI before merge;
+- workflow permissions narrowed to read-only unless a job needs more;
+- no long-lived npm token in Actions for publish;
+- npm trusted publishing via OIDC where possible;
+- secret scanning and push protection enabled where available;
+- `SECURITY.md`, `CONTRIBUTING.md`, `LICENSE`, and clear issue flow;
+- periodic OpenSSF Scorecard or equivalent review.
+
+Nice-to-have after public launch:
+
+- dependency update automation;
+- CodeQL or comparable SAST;
+- release provenance and staged publishing where practical;
+- signed releases when the release process matures.
+
+## Humanish Application
+
+For `humanish`, the honest standard is:
+
+- Keep `docs/ramp/` and `docs/goals/` if they are public-safe. They are essential
+  project memory for future coding agents and contributors.
+- Keep the package docs and skill docs focused on public install, public-safe
+  examples, and synthetic proof.
+- Do not commit `.humanish/`, `.firecrawl/`, screenshots from private systems,
+  raw run bundles, private transcripts, local env files, or packed tarballs.
+- Treat `dist` and source maps as public and scan them.
+- Treat the README screenshot as public and checksum-gated.
+- Allow a maintainer-approved public email in commit metadata; do not classify it
+  as a secret.
+- Rewrite history only for actual sensitive data, private source, or private
+  identity/customer data that remains materially risky.
+
+## Practical Checklist
+
+Before making the repository public or cutting a public package:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm release:check
+git diff --check
+npm pack --dry-run --json
+```
+
+Also verify in GitHub:
+
+- `main` branch protection/ruleset is active;
+- secret scanning and push protection are enabled where available;
+- publish workflow uses OIDC trusted publishing;
+- failed workflow logs do not contain real secrets or private data;
+- visible issues, PRs, labels, and project metadata do not expose private context.
+
+If a check fails, classify it before reacting:
+
+1. Secret/PHI/private source? Rotate/revoke first, then consider history rewrite.
+2. Package leak or private artifact? Remove from package/tree and rerun gates.
+3. Unknown private identity metadata? Approve, redact, or rewrite based on risk.
+4. Public maintainer metadata? Usually allowlist and document.
+5. Sloppy public docs? Rewrite, do not delete useful project memory.