lossless-openclaw-orchestrator 1.0.0 → 1.1.0

package/AGENTS.md

@@ -0,0 +1,55 @@
+# LCO Agent Instructions
+
+## Repository Agent Quick Start
+
+If you are a coding agent working in this repository:
+
+1. Read README.md for the public product promise and proof boundary.
+2. Read CONTRIBUTING.md for issue routing, validation, evidence, and PR
+   expectations.
+3. Read docs/SETUP.md before changing install, OpenClaw, MCP, or first-run
+   behavior.
+4. Read SECURITY.md before touching vulnerability reporting, secrets, auth,
+   control, or private-data handling.
+5. Create or reuse a GitHub issue before meaningful implementation work.
+6. Write or update a failing test, smoke, or eval scenario before the minimal
+   implementation.
+7. Do not commit raw transcripts, private SQLite DBs, screenshots with private
+   data, tokens, cookies, connector URLs, or credentials.
+8. Update the issue before handoff, merge, pause, or external-review wait.
+
+## Shared Owned-Repo Policy
+
+- Use `100yenadmin/codex-operating-kit` for the shared issue/epic/milestone/sprint policy, PR review-thread lifecycle, and release changelog standard.
+- Shared rollout tracker: https://github.com/100yenadmin/codex-operating-kit/issues/5
+- Shared kit merge: `100yenadmin/codex-operating-kit@d1bd004a85da6967041765b46fcb8885a88b802b`
+- For meaningful GitHub work, create or reuse an issue before implementation, link PRs to the issue, and update the issue/tracker before handoff, merge, or pause.
+- Before merge, release, or readiness claims, query current-head review threads and separate resolvable review threads from top-level bot comments and check annotations.
+- P0-P2 current actionable review threads block merge/release unless fixed, proven false-positive, or explicitly escalated. P3/advisory threads still need terminal disposition.
+- Releases, prereleases, and release-affecting PRs must lead with human-readable user/operator outcomes and keep proof, evidence, artifact identity, and rollback details in a compact verification tail.
+- Keep LCO-specific beta claim tiers, release proof, demo status, and source-authority gates in this repo's runbooks. The shared kit supplies the common operating spine only.
+
+## LCO Release Gates
+
+- Read `docs/BETA_RELEASE_RUNBOOK.md`, `docs/RELEASE_CHECKLIST.md`, `docs/SOURCE_AUTHORITY_PROFILE.md`, and `docs/CLAIM_AUDIT.md` before claiming release or beta readiness.
+- Require `loo release preflight --strict` to report a structured `approved_live_control_smoke` marker before any beta/release claim that includes live-control or working-app proof.
+- Do not treat merged code, local smoke, or docs-only proof as a beta release by itself.
+- Do not rewrite historical release notes or resolve historical PR residue without a separate issue.
+
+Do not widen LCO public claims from this file. Live Codex control, GUI mutation,
+Claude parity, npm publish, GitHub Release creation, and 1.0 readiness require
+their own scoped proof gates.
+
+## Public Documentation Placement
+
+- Keep `README.md` as the public landing page: product value, install, setup,
+  first workflow, OpenClaw/MCP entrypoints, safety boundaries, and links.
+- Keep detailed first-run instructions in `docs/SETUP.md`.
+- Keep OpenClaw plugin/operator details in `docs/OPENCLAW_PLUGIN.md`.
+- Keep agent-facing workflow instructions in
+  `skills/lossless-openclaw-orchestrator/SKILL.md`.
+- Keep repo-agent operating rules, release discipline, and source-of-truth
+  policy in this `AGENTS.md`.
+- Do not put active sprint ledgers, long issue history, exhaustive release-gate
+  command inventories, or internal agent maintenance loops into the public
+  README. Link `VISION.md`, GitHub trackers, or runbooks instead.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+LCO is a small, safety-sensitive open-source project. The community standard is
+simple: be respectful, be specific, and keep reports public-safe.
+
+## Expected Behavior
+
+- Treat contributors, users, and maintainers with respect.
+- Keep disagreement focused on evidence, behavior, safety, and user impact.
+- Assume good intent while still verifying claims.
+- File one issue per problem and use the appropriate issue form.
+- Redact secrets, local transcripts, customer data, screenshots, and private
+  database contents before posting.
+
+## Unacceptable Behavior
+
+- Harassment, threats, personal attacks, or discriminatory language.
+- Publishing private credentials, local transcripts, customer data, or
+  vulnerability details in public issues.
+- Pressuring maintainers to bypass safety, privacy, approval, or release gates.
+- Spam, low-signal automated reports, or scanner output without a reproducible
+  LCO impact.
+
+## Reporting
+
+For community conduct concerns, contact the project owner privately through the
+GitHub profile linked from this repository.
+
+For security vulnerabilities, use [SECURITY.md](SECURITY.md). Do not disclose
+unpatched vulnerabilities in public issues or pull requests.
+
+Maintainers may edit, hide, lock, or remove public content that exposes private
+data, creates an active security risk, or violates this code.

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing
+
+Thanks for helping make local agent orchestration safer and less exhausting.
+LCO is local-first infrastructure for Codex-heavy workflows, so useful
+contributions are precise, well-scoped, and public-safe.
+
+## Quick Links
+
+- [Setup guide](docs/SETUP.md)
+- [Repository agent instructions](AGENTS.md)
+- [OpenClaw plugin guide](docs/OPENCLAW_PLUGIN.md)
+- [Privacy policy](docs/PRIVACY.md)
+- [Security policy](SECURITY.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Vision and proof boundary](VISION.md)
+
+## Issue Routing
+
+Use the GitHub issue forms and keep one problem per issue.
+
+| Situation | Use | Required evidence |
+| --- | --- | --- |
+| Product bug, regression, crash, or wrong output | Bug report | Version, OS, command/tool, minimal repro, expected result, actual result, redacted logs |
+| Missing, stale, or contradictory docs | Docs bug report | Affected path, current wording, expected wording, setup or user impact |
+| New capability or product improvement | Feature request | User story, problem, proposed behavior, alternatives, safety boundary |
+| New app/runtime adapter | Adapter request | Target runtime, read/index path, control capability needed, local storage/protocol, proof available |
+| Upstream API or protocol drift | Protocol drift | Surface, version/commit, observed drift, impact, proposed compatibility gate |
+| Unsafe control behavior | Unsafe control report | Tool/command, whether dry-run happened, approval_audit_id behavior, no secrets |
+
+Security vulnerabilities should be reported privately through
+[SECURITY.md](SECURITY.md), not as public issues.
+
+## Before You Open A PR
+
+1. Create or reuse a GitHub issue and include `Closes #<issue>` or
+   `Related: #<issue>` in the PR.
+2. Read [docs/SETUP.md](docs/SETUP.md) and run the narrowest local setup needed
+   for your change.
+3. Write or update a failing test, smoke, or eval scenario before implementing
+   non-trivial behavior.
+4. Keep the PR focused on one user-visible or maintainer-visible problem.
+5. Keep public claims inside the documented safety boundary.
+
+Good First Contributions:
+
+- docs setup gaps and clearer troubleshooting
+- redacted fixture improvements
+- CLI help wording
+- issue template improvements
+- narrow tests for public-safe redaction, setup status, and scorecards
+- small OpenClaw plugin manifest/doc corrections
+
+Avoid refactor-only PRs unless a maintainer asked for that refactor as part of
+an active issue.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run check
+```
+
+For fast iteration, run the focused test file that owns your change before
+running `npm run check`.
+
+Use redacted fixtures for tests. Do not commit raw Codex transcripts, raw local
+Codex, Claude Code, OpenClaw, browser, customer session data, raw SQLite DBs,
+screenshots containing private data, tokens, cookies, API keys, connector URLs,
+or credentials.
+
+## Validation And Evidence
+
+Every meaningful PR should name the proof it ran:
+
+- failing test, smoke, or eval scenario used to define the change
+- focused validation command
+- `npm run check`, or why CI is the right place for heavier validation
+- OpenClaw gateway dogfood when the change affects installed `loo_*` tools
+- evidence path such as `evidence/YYYY-MM-DD/issue-<number>/`, or the
+  maintainer-provided external evidence path linked from the issue
+
+Evidence should contain public-safe summaries, counts, refs, hashes, setup
+status, blocker codes, and command names. It must not contain raw Codex
+transcripts, raw prompts, customer data, private DBs, secrets, or screenshots
+with sensitive content.
+
+## Agent-Authored Contributions
+
+Agent-authored PRs are welcome when the agent leaves a human-reviewable trail.
+If a coding agent authored or materially edited the PR:
+
+- say so in the PR body
+- keep the issue updated before handoff, merge, or pause
+- include the exact focused validation commands
+- summarize safety boundaries and restricted actions not performed
+- resolve or reply to bot review conversations after addressing them
+- do not claim release readiness, live control, GUI mutation, Claude parity, or
+  customer readiness unless the matching proof gates pass
+
+Agents should read [AGENTS.md](AGENTS.md) before editing this repository.
+
+## Pull Request Expectations
+
+- Preserve local-only defaults.
+- Preserve safe summaries before raw expansion.
+- Preserve source refs instead of absolute transcript paths in public output.
+- Preserve dry-run plus matching `approval_audit_id` before live control.
+- Add or update tests for extraction, search, approval gates, setup status,
+  scorecards, or adapter behavior when those surfaces change.
+- Do not add cloud sync, hidden control, transcript upload paths, permission
+  bypasses, or generic GUI mutation without a separate design issue and proof
+  boundary.
+
+## Review Threads
+
+Review conversations are author-owned. If a bot or human leaves an actionable
+thread:
+
+- verify it against current code before changing anything
+- fix real issues with focused tests
+- explain false positives with concrete file/test evidence
+- reply with the terminal outcome
+- resolve the thread when the concern is handled
+
+Do not leave "fixed" bot threads for maintainers to clean up.
+
+## Safety Boundaries
+
+LCO is Codex-first and local-first. Public contributions must not widen these
+claims without explicit evidence:
+
+- no full Claude Code parity
+- no cloud sync
+- no unattended desktop takeover
+- no permission bypass
+- no enterprise/customer-ready security claim
+- no generic GUI mutation
+- no Codex GUI mutation as a stable public claim
+
+When in doubt, file a design issue first.