# Pre-Launch Fixes & Improvements

**Repository Readiness Assessment: 82/100**

This document provides a ranked list of fixes and improvements to take the aport-agent-guardrails repository to 100/100 launch readiness. Items are ranked by impact, criticality, and ROI for implementation.

**Current Status:**
- ✅ All 9 tests passing
- ✅ Core functionality complete (local + API modes)
- ✅ Comprehensive documentation
- ✅ OpenClaw plugin implementation (545 lines, well-tested)
- ⚠️ Missing standard repository files
- ⚠️ Version mismatch between packages
- ⚠️ Launch execution gate not fully satisfied

---

## 🔴 CRITICAL (Blockers - Must Fix Before Public Launch)

### 1. **Add SECURITY.md** ⭐⭐⭐⭐⭐
**Impact:** Critical for GitHub trust indicators & security best practices
**Effort:** 15 minutes
**ROI:** Very High

**Why:** GitHub shows a security tab; missing SECURITY.md looks unprofessional. Required for responsible disclosure.

**Action:**
```bash
# Create /Users/uchi/Downloads/projects/aport-agent-guardrails/SECURITY.md
```

**Content template:**
```markdown
# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 1.0.x   | :white_check_mark: |
| 0.1.x   | :white_check_mark: |

## Reporting a Vulnerability

**DO NOT** open public GitHub issues for security vulnerabilities.

Please report security vulnerabilities to: security@aport.io

Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)

We aim to respond within 48 hours and provide a fix within 7 days for critical issues.

## Security Features

- **Fail-closed by default**: Errors block tool execution
- **Tamper-evident audit logs**: SHA-256 content hashing
- **Deterministic enforcement**: Platform-level, AI cannot bypass
- **Local-first option**: No network dependency required
```

---

### 2. **Fix Version Mismatch Between Packages** ⭐⭐⭐⭐⭐
**Impact:** Critical - Confusing for users, breaks npm publish expectations
**Effort:** 2 minutes
**ROI:** Very High

**Issue:** Root package.json shows `v0.1.0` but plugin package shows `v1.0.0`

**Files:**
- `/Users/uchi/Downloads/projects/aport-agent-guardrails/package.json` → version: "0.1.0"
- `/Users/uchi/Downloads/projects/aport-agent-guardrails/extensions/openclaw-aport/package.json` → version: "1.0.0"

**Recommendation:** Sync both to `1.0.0` for launch (you're ready for 1.0, not 0.1)

**Action:**
```json
// In package.json, change line 3:
"version": "1.0.0"
```

**Rationale:**
- All tests passing
- Documentation complete
- Production-ready features
- Launch-ready = 1.0.0

---

### 3. **Verify Repository is Public** ⭐⭐⭐⭐⭐
**Impact:** Critical - Can't launch if repo is private
**Effort:** 30 seconds
**ROI:** Infinite

**Current Status:** Unknown (per QUICK_LAUNCH_CHECKLIST.md, repo may still be private)

**Action:**
1. Go to GitHub repo settings
2. Make repository public
3. Verify: https://github.com/aporthq/aport-agent-guardrails (should not 404)
4. Test all README links work

---

### 4. **Complete Launch Execution Gate** ⭐⭐⭐⭐⭐
**Impact:** Critical - Per LAUNCH_READINESS_CHECKLIST.md, cannot claim "5-minute setup" without this
**Effort:** 30 minutes (testing + screenshot)
**ROI:** Very High (prevents embarrassing launch failures)

**Per docs/launch/LAUNCH_READINESS_CHECKLIST.md:119-128, must verify:**

- [ ] Passport allows normal commands (installer sets `allowed_commands: ["*"]`)
- [ ] Plugin config correct (paths to guardrail script and passport)
- [ ] No policy denials for normal use (mkdir, ls, etc. get ALLOW)
- [ ] Messaging works (if claimed in launch post)
- [ ] **Evidence artifact captured** (screenshot showing ALLOW + DENY)

**Action:**
1. Run: `./bin/openclaw` to verify setup works end-to-end
2. Test: `~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'` → should show ALLOW
3. Test: `~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'` → should show DENY
4. **Capture screenshot** of terminal showing both results
5. Save to `docs/launch/evidence-allow-deny.png`

**Do not launch guardrail post without this screenshot.**

---

## 🟠 HIGH PRIORITY (Strong Impact - Fix Before/During Launch Week)

### 5. **Add CODE_OF_CONDUCT.md** ⭐⭐⭐⭐
**Impact:** High - Community health indicator, GitHub badge
**Effort:** 10 minutes
**ROI:** High

**Why:** Shows project is community-friendly; GitHub displays badge

**Action:**
Use Contributor Covenant (standard):
```bash
curl https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md -o CODE_OF_CONDUCT.md
# Then edit contact email to: conduct@aport.io
```

---

### 6. **Add .npmignore** ⭐⭐⭐⭐
**Impact:** High - Prevents publishing unnecessary files to npm
**Effort:** 5 minutes
**ROI:** High

**Why:** Without this, `npm publish` includes test fixtures, launch docs, etc. (bloat)

**Action:**
Create `/Users/uchi/Downloads/projects/aport-agent-guardrails/.npmignore`:

```
# Development
.git
.github
.gitignore
.gitmodules

# Tests
tests/
*.test.js
test.js

# Docs (launch-specific)
docs/launch/
_plan/
APORT_GOOSE_ARCHITECTURE.md

# Examples (keep in repo, exclude from npm)
examples/

# Build artifacts
node_modules/
*.log
.DS_Store

# Local overrides
local-overrides/

# External (submodules - users should git clone, not npm install)
external/
```

**Also create for plugin:** `/Users/uchi/Downloads/projects/aport-agent-guardrails/extensions/openclaw-aport/.npmignore`:
```
test.js
*.test.js
.DS_Store
```

---

### 7. **Add GitHub Workflows (CI/CD)** ⭐⭐⭐⭐
**Impact:** High - Builds trust, catches bugs before merge
**Effort:** 20 minutes
**ROI:** High

**Current Status:** Only `ci.yml` and `release.yml` exist in `.github/workflows/`

**Action:** Verify existing workflows are complete and add missing ones:

**Check ci.yml includes:**
- Run `npm test` (main repo)
- Run `npm test` in `extensions/openclaw-aport/`
- Run bash tests: `make test`
- Verify submodules load: `git submodule update --init --recursive`

**Add publish-plugin.yml** for npm publish automation:
```yaml
name: Publish Plugin to npm

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - name: Publish OpenClaw Plugin
        run: |
          cd extensions/openclaw-aport
          npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

---

### 8. **Update CHANGELOG.md with 1.0.0 Release** ⭐⭐⭐⭐
**Impact:** High - Shows project maturity, helps users understand what changed
**Effort:** 10 minutes
**ROI:** High

**Current:** CHANGELOG.md at line 28 shows `[0.1.0] - 2026-02-14` as latest release

**Action:** Add `## [1.0.0] - 2026-02-XX` section with comprehensive release notes:

```markdown
## [1.0.0] - 2026-02-15

### 🎉 Major Release - Production Ready

#### Added - Core Features
- **OpenClaw Plugin**: Deterministic `before_tool_call` enforcement (545 lines, fully tested)
  - Local mode (bash evaluator, no network required)
  - API mode (APort cloud API integration)
  - Fail-closed by default with configurable fail-open
  - Per-tool-call verification (no caching/reuse)
  - Recursive guardrail detection (delegates to inner tool)
  - Tamper-evident decisions (SHA-256 content hashing)

#### Added - Security & Policies
- 40+ built-in security patterns (command injection, path traversal, etc.)
- 4 OpenClaw-compatible policies:
  - `system.command.execute.v1` with allowed_commands allowlist
  - `mcp.tool.execute.v1` for MCP tools
  - `agent.session.create.v1` for agent spawning
  - `agent.tool.register.v1` for dynamic tool registration
- Tool-to-policy mapping (exec, git.*, messaging.*, etc.)
- Kill switch support (global emergency stop)

#### Added - Documentation
- Comprehensive setup guide: `docs/QUICKSTART_OPENCLAW_PLUGIN.md`
- Plugin-specific README: `extensions/openclaw-aport/README.md` (420+ lines)
- Tool/policy mapping reference: `docs/TOOL_POLICY_MAPPING.md`
- OpenClaw compatibility guide: `docs/OPENCLAW_COMPATIBILITY.md`
- Verification methods: `docs/VERIFICATION_METHODS.md`
- Launch strategy and checklists in `docs/launch/`

#### Added - Developer Tools
- Interactive setup wizard: `bin/openclaw` (23KB, full UX)
- Passport creation wizard: `bin/aport-create-passport.sh` (OAP v1.0)
- Status dashboard: `bin/aport-status.sh` (health checks, recent activity)
- Dual evaluators: `aport-guardrail-bash.sh` (local) and `aport-guardrail-api.sh` (API)

#### Added - Testing & Quality
- 9 test suites, 100% passing:
  - API evaluator tests
  - Full flow tests
  - Kill switch tests
  - OAP v1 compliance tests
  - Passport creation/validation tests
  - Plugin CLI tests
- Plugin unit tests: `extensions/openclaw-aport/test.js` (integrity, canonicalization, mapping)
- Test fixtures with realistic passport examples

#### Added - GitHub Templates
- Issue templates (bug report, feature request, security)
- Pull request template
- CI/CD workflows (ci.yml, release.yml)

#### Changed
- Version bumped to 1.0.0 (production-ready)
- Plugin config: installer now sets `allowed_commands: ["*"]` by default (no manual editing)
- Improved exec handling: detects recursive guardrail invocations, delegates to inner tool
- Enhanced error messages: shows OAP codes, suggests fixes (e.g., add to allowed_commands)

#### Performance
- P95 latency: 268ms (local mode)
- Mean latency: 178ms
- Success rate: 100%
- Zero failures in test suite

#### Breaking Changes
None (initial 1.0.0 release)

### [0.1.0] - 2026-02-14
(Initial development release - see previous entry)
```

---

### 9. **Add .editorconfig** ⭐⭐⭐
**Impact:** Medium-High - Ensures consistent formatting across contributors
**Effort:** 3 minutes
**ROI:** High (prevents formatting PR noise)

**Action:** Create `.editorconfig`:
```ini
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{js,json}]
indent_style = space
indent_size = 2

[*.{sh,bash}]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false
max_line_length = off

[Makefile]
indent_style = tab
```

---

## 🟡 MEDIUM PRIORITY (Quality of Life - Fix During Launch Week)

### 10. **Create Plugin npm README** ⭐⭐⭐
**Impact:** Medium - Better npm package page presentation
**Effort:** 5 minutes
**ROI:** Medium

**Why:** The plugin's README.md is comprehensive (420 lines) but could have a shorter npm-focused intro

**Action:** The existing `extensions/openclaw-aport/README.md` is already excellent. Just verify it renders well on npm:
1. Preview: https://www.npmjs.com/package/markdown-preview
2. Ensure badges at top (version, license, downloads)

**Optional:** Add badges to plugin README:
```markdown
[![npm version](https://badge.fury.io/js/%40aporthq%2Fopenclaw-aport.svg)](https://www.npmjs.com/package/@aporthq/openclaw-aport)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Node Version](https://img.shields.io/node/v/@aporthq/openclaw-aport)](package.json)
```

---

### 11. **Add Examples to README.md** ⭐⭐⭐
**Impact:** Medium - Faster user onboarding
**Effort:** 10 minutes
**ROI:** Medium

**Current:** README.md has good structure but could use inline examples

**Action:** Add "Quick Example" section after "Quick Start" in README.md:

```markdown
## Quick Example

**Test policy enforcement locally:**

```bash
# Allow a safe command
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'
# Exit: 0 (ALLOW)

# Block a dangerous pattern
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'
# Exit: 1 (DENY - blocked pattern detected)
```

**Check your passport status:**

```bash
~/.openclaw/.skills/aport-status.sh
```

Shows:
- ✅ Passport status and expiration
- 🔐 Active capabilities
- ⚙️ Configured limits
- 📊 Recent activity log
```

---

### 12. **Create UPGRADE.md Guide** ⭐⭐⭐
**Impact:** Medium - Helps users migrate between versions
**Effort:** 15 minutes
**ROI:** Medium (future-proofing)

**Why:** As you release 1.1.0, 2.0.0, users need migration guides

**Action:** Create `docs/UPGRADE.md`:
```markdown
# Upgrade Guide

## Upgrading from 0.1.0 to 1.0.0

### Breaking Changes
None - 1.0.0 is the first production release

### New Features
- OpenClaw plugin with `before_tool_call` enforcement
- API mode support (in addition to local mode)
- Enhanced exec handling with recursive guardrail detection
- Improved error messages with OAP codes

### Migration Steps

**If upgrading from 0.1.0:**

1. Update your installation:
   ```bash
   git pull
   git submodule update --init --recursive
   ```

2. Re-run setup to install plugin:
   ```bash
   ./bin/openclaw
   ```

3. Update OpenClaw config (if using plugin):
   ```yaml
   plugins:
     entries:
       openclaw-aport:
         enabled: true
         config:
           mode: local  # or "api"
           passportFile: ~/.openclaw/passport.json
   ```

4. Verify passport has `allowed_commands`:
   ```bash
   jq '.limits.system.command.execute.allowed_commands' ~/.openclaw/passport.json
   ```
   If empty or missing, re-run passport wizard or add manually.

**No other changes required.**
```

---

### 13. **Add FAQ Section to Main README** ⭐⭐⭐
**Impact:** Medium - Reduces support burden
**Effort:** 15 minutes
**ROI:** Medium-High

**Action:** Add FAQ section before "Resources" in README.md:

```markdown
## Frequently Asked Questions

### Does this slow down my agent?

No. Local mode adds ~180ms mean latency (268ms P95). Not noticeable in practice. Every call is fresh (no caching), so you always verify against current passport state.

### Can the agent bypass this?

**With plugin:** No. Platform enforces via `before_tool_call` hook. Agent never sees the guardrail—just gets allowed/denied.

**Without plugin (AGENTS.md only):** Yes, via prompt injection. Use the plugin for deterministic enforcement.

### What if I need to allow a new command?

Edit `~/.openclaw/passport.json`:
```json
"limits": {
  "system.command.execute": {
    "allowed_commands": ["mkdir", "npm", "YOUR_COMMAND"]
  }
}
```
Next tool call uses the updated passport. Takes 30 seconds.

### Does this work with other frameworks (not OpenClaw)?

The plugin is OpenClaw-specific. The generic evaluator (`bin/aport-guardrail-bash.sh`, `bin/aport-guardrail-api.sh`) works anywhere (Node, Python, bash). See `docs/` for integration examples.

### What's the difference between local and API mode?

| Feature | Local Mode | API Mode |
|---------|------------|----------|
| Network Required | No | Yes |
| OAP Compliance | Subset (bash evaluator) | Full (JSON Schema, assurance levels) |
| Signatures | Unsigned | Ed25519 signed (API) |
| Kill Switch | Local file | Cloud-based (global) |
| Best For | Privacy, offline, dev | Production, audit, teams |

Both modes enforce the same policies. Local is faster; API has more features.
```

---

## 🟢 LOW PRIORITY (Nice to Have - Post-Launch)

### 14. **Add .prettierrc for Consistent Formatting** ⭐⭐
**Impact:** Low - Code formatting consistency
**Effort:** 3 minutes
**ROI:** Low (mostly for contributors)

**Action:** Create `.prettierrc`:
```json
{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 80,
  "arrowParens": "always"
}
```

And add to package.json:
```json
"devDependencies": {
  "prettier": "^3.0.0"
},
"scripts": {
  "format": "prettier --write \"**/*.{js,json,md}\"",
  "format:check": "prettier --check \"**/*.{js,json,md}\""
}
```

---

### 15. **Create ROADMAP.md** ⭐⭐
**Impact:** Low-Medium - Shows project direction
**Effort:** 20 minutes
**ROI:** Low (but good for community engagement)

**Action:** Create public-facing `ROADMAP.md` (summary of internal plans):

```markdown
# Roadmap

## Released (1.0.0) ✅
- OpenClaw plugin with deterministic enforcement
- Local + API evaluation modes
- 4 OpenClaw policies (system.command.execute, mcp.tool.execute, etc.)
- 40+ security patterns
- Comprehensive documentation

## Near Term (Q1 2026)
- [ ] Audit log chaining (SHA-256, tamper-evident chain)
- [ ] Rate limiting enforcement (msgs_per_min, prs_per_day)
- [ ] Preset passport templates (developer, CI/CD, enterprise)
- [ ] npm publish for easy installation
- [ ] Video walkthrough (5-minute setup)

## Medium Term (Q2 2026)
- [ ] IronClaw adapter (bring policies to IronClaw)
- [ ] Web dashboard for passport management
- [ ] Team passports (share policies across team)
- [ ] Policy pack marketplace
- [ ] Homebrew formula (brew install aport-agent-guardrails)

## Long Term (Q3-Q4 2026)
- [ ] Go adapter
- [ ] Python adapter
- [ ] GitHub Action for CI/CD guardrails
- [ ] VS Code extension (inline policy hints)
- [ ] Policy testing framework
- [ ] OpenAPI-based policy generation

## Community Requests
Have an idea? [Open a discussion](https://github.com/aporthq/aport-agent-guardrails/discussions)
```

---

### 16. **Add Badges to Main README** ⭐⭐
**Impact:** Low - Visual trust indicators
**Effort:** 5 minutes
**ROI:** Low

**Action:** Add to top of README.md (after title):

```markdown
# APort Agent Guardrails

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](package.json)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests/)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](package.json)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-%3E%3D2026.2.0-blue.svg)](extensions/openclaw-aport/package.json)

**Deterministic pre-action authorization for AI agents.**
```

---

### 17. **Create Docker Image** ⭐⭐
**Impact:** Low-Medium - Easier deployment for some users
**Effort:** 30 minutes
**ROI:** Low (most users will git clone)

**Action:** Create `Dockerfile`:
```dockerfile
FROM node:18-alpine

RUN apk add --no-cache bash jq git

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .

RUN git submodule update --init --recursive

EXPOSE 8787

CMD ["npm", "run", "server"]
```

And `docker-compose.yml`:
```yaml
version: '3.8'
services:
  aport-agent-guardrails:
    build: .
    ports:
      - "8787:8787"
    volumes:
      - ./config:/root/.openclaw:ro
      - ./decisions:/app/decisions
    environment:
      - APORT_API_URL=https://api.aport.io
```

---

### 18. **Add Contributing Guidelines Detail** ⭐
**Impact:** Low - Better for contributors
**Effort:** 10 minutes
**ROI:** Low (existing CONTRIBUTING.md is good)

**Current:** CONTRIBUTING.md exists at 1779 bytes

**Action:** Enhance with:
- Development setup steps
- How to run tests locally
- Code style guidelines
- How to add a new policy
- How to test the plugin locally

---

## 📊 Summary Matrix

| Priority | # Items | Est. Total Time | Total Impact |
|----------|---------|----------------|--------------|
| 🔴 Critical | 4 | 1.5 hours | Blocks Launch |
| 🟠 High | 5 | 1.5 hours | Strong Impact |
| 🟡 Medium | 4 | 1 hour | Quality of Life |
| 🟢 Low | 5 | 1.5 hours | Nice to Have |
| **TOTAL** | **18** | **~5.5 hours** | **Launch Ready** |

---

## 🎯 Recommended Implementation Order

### Pre-Launch (Must Do - Next 2 Hours)
1. ✅ Add SECURITY.md (15 min)
2. ✅ Fix version mismatch to 1.0.0 (2 min)
3. ✅ Verify repo is public (1 min)
4. ✅ Complete execution gate + capture screenshot (30-60 min)
5. ✅ Add CODE_OF_CONDUCT.md (10 min)
6. ✅ Add .npmignore (5 min)

**After these 6 items: Ready to launch guardrail post** ✅

### Launch Week (Should Do - Next 2 Hours)
7. Update CHANGELOG.md for 1.0.0 (10 min)
8. Verify/enhance CI workflows (20 min)
9. Add .editorconfig (3 min)
10. Add Quick Example to README (10 min)

### Post-Launch (Nice to Have - Ongoing)
11-18. Everything else as time permits

---

## 🚀 Launch Readiness Score

**Current: 82/100**

After completing Critical + High priority items: **95/100** (Launch Ready)

After completing all Medium priority items: **98/100** (Polished)

After completing all items: **100/100** (Perfect)

---

## 📝 Quick Wins (< 15 min each)

If short on time, prioritize these for maximum impact:

1. **SECURITY.md** (15 min) - Critical missing file
2. **Version sync** (2 min) - Prevents confusion
3. **Execution gate screenshot** (30 min if setup works) - Required for launch post
4. **.npmignore** (5 min) - Prevents npm bloat
5. **.editorconfig** (3 min) - Clean contributor experience
6. **Badges to README** (5 min) - Visual polish

**Total: ~1 hour for massive polish improvement**

---

## Notes

- All tests passing (9/9) ✅
- Plugin tests passing (canonicalize, integrity, mapping) ✅
- Documentation is comprehensive and well-written ✅
- Code quality is high (545-line plugin with good structure) ✅
- No TODOs/FIXMEs found in codebase ✅

**Main gaps:** Standard repository files (SECURITY.md, CODE_OF_CONDUCT.md, .npmignore) and version consistency.

**Recommendation:** Focus on Critical items first (4 items, ~1.5 hours), then launch. High priority items can be done during launch week based on early feedback.

---

**Last Updated:** 2026-02-15
**Reviewer:** Claude Code Comprehensive Audit
**Next Review:** After implementing Critical fixes