diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5120fc4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,151 @@ +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the +dignity, rights, and contributions of all individuals, regardless of +characteristics including race, ethnicity, caste, color, age, physical +characteristics, neurodiversity, disability, sex or gender, gender identity or +expression, sexual orientation, language, philosophy or religion, national or +social origin, socio-economic position, level of education, or other status. +The same privileges of participation are extended to everyone who participates +in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our +community's expectations for positive behavior. We also understand that our +words and actions may be interpreted differently than we intend based on +culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each +other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of + gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our + community**. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, +threats, and promotion of these behaviors are violations of this Code of +Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in + unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments + directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone's personality or + behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered + inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality.** Sharing or acting on someone's personal or + private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other + harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or + pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content + you contribute. +3. **Promotional materials.** Sharing marketing or other commercial content in + a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content + which includes, links, or describes any other restricted behaviors. + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their +best to collaborate. Not every conflict represents a code of conduct +violation, and this Code of Conduct reinforces encouraged behaviors and norms +that can help avoid conflicts and minimize harm. + +Use the repository host's private reporting form on the Security tab to report +a possible violation. Start the report title with `Code of Conduct:`. Do not +open a public issue. The repository owner serves as the Community Moderator +and receives these private reports. If a report concerns the repository owner, +use GitHub's content-reporting or support channel instead. + +The Community Moderator takes reports of violations seriously and will make +every effort to respond in a timely manner. The moderator will investigate +reports by reviewing relevant messages, logs, recordings, or witness accounts. +The moderator will keep investigation and enforcement actions as transparent +as possible while prioritizing safety and confidentiality. Enforcement actions +are carried out in private with the involved parties, but communicating to the +whole community may be part of a mutually agreed resolution. + +## Addressing and Repairing Harm + +If an investigation finds that this Code of Conduct has been violated, the +following enforcement ladder may be used to determine how best to repair harm. +The decision depends on the incident's impact on the people involved and the +community as a whole. Depending on the severity of a violation, lower rungs on +the ladder may be skipped. + +1. **Warning** + 1. Event: A violation involving a single incident or series of incidents. + 2. Consequence: A private, written warning from the Community Moderator. + 3. Repair: Examples include a private written apology, acknowledgement of + responsibility, and seeking clarification on expectations. +2. **Temporarily Limited Activities** + 1. Event: A repeated violation that previously resulted in a warning, or the + first occurrence of a more serious violation. + 2. Consequence: A private, written warning with a time-limited cooldown + period. The period may limit particular communication channels or + interactions with particular community members. + 3. Repair: Examples include making an apology, reflecting on actions and + impact, and being thoughtful about re-entering community spaces. +3. **Temporary Suspension** + 1. Event: A pattern of repeated violations that warnings did not resolve, or + a single serious violation. + 2. Consequence: A private written warning with conditions for return from + suspension. + 3. Repair: Examples include respecting the spirit of the suspension, meeting + the conditions for return, and reintegrating thoughtfully. +4. **Permanent Ban** + 1. Event: A pattern that other steps did not resolve, or a violation so + serious that the moderator cannot keep the community safe with this + person as a member. + 2. Consequence: Access to all community spaces, tools, and communication + channels is removed. Permanent bans should be rare and supported by + strong reasoning. + 3. Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is a guideline. It does not limit the Community +Moderator's discretion and judgment when acting in the community's best +interests. + +## Scope + +This Code of Conduct applies within all community spaces. It also applies when +an individual officially represents the community in public or other spaces. +Examples include using an official email address, posting through an official +social account, or acting as an appointed representative at an online or +offline event. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, +permanently available at +[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and +licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). +The enforcement ladder was inspired by the work of +[Mozilla's code of conduct team](https://github.com/mozilla/inclusion). + +For more guidance, see the Contributor Covenant +[FAQ](https://www.contributor-covenant.org/faq), +[translations](https://www.contributor-covenant.org/translations), and +[resources](https://www.contributor-covenant.org/resources). diff --git a/README.md b/README.md index 5d4df58..c50b1a7 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,33 @@ go install github.com/nstranquist/wip-commit/cmd/wip@v0.1.0-beta.1 Before you run that command, verify that the tag exists at that public address. +## Quick start + +Build the current checkout, then start the setup wizard inside the Git +repository where you want to capture work: + +```text +go build -trimpath -o ./bin/wip ./cmd/wip +./bin/wip init +``` + +The wizard prints the lane environment command. Load it in the agent shell, +stage only owned paths, review the proposed groups, and capture them: + +```text +eval "$(./bin/wip env --lane )" +git add -- ... +./bin/wip plan +./bin/wip commit +./bin/wip release +``` + +Use a linked worktree when one agent should own the complete checkout. Use +shared mode when cooperating agents need disjoint path leases in one checkout. +Automation should pass an exact JSON plan. Start with +[examples/shared-split-plan.json](examples/shared-split-plan.json) and replace +every message, path, and verification command with reviewed project values. + ## Use the agent skill The portable skill is in [skills/wip-commit](skills/wip-commit). Install that @@ -136,7 +163,27 @@ The command uses `git worktree add --detach`. It refuses to replace an existing directory. If an existing directory contains a matching linked worktree at the requested base, the command reuses it. -## Capture work +## Configuration + +`wip` has no repository configuration file and no background service. The +`wip init` command records the selected lane, worktree, owner, and path leases +below the repository's common Git directory. Linked worktrees therefore share +one coordination domain. + +Use `--repo-dir` to select a repository without changing directories. Use +`--json` when a program needs typed results. `wip env` exports `WIP_LANE`, +`WIP_AGENT`, and `WIP_SESSION` for later commands. An explicit +`GIT_INDEX_FILE` selects the caller's source index; other inherited +repository-routing variables do not override the selected repository. + +Commit plans hold per-group verification commands and optional timeouts. The +default verification and hook timeout is two minutes, and the maximum is 24 +hours. Keep secrets and machine-specific paths out of plan files and commit +messages. + +## Usage + +### Capture work Load the lane identity in each agent shell: @@ -317,6 +364,32 @@ Reconciliation compares the target ref, every parent, tree, message, changed pat allowed scope, and final tree before it updates lane metadata. Exact retries are idempotent. +## Troubleshooting + +Start with structured state evidence: + +```text +wip --json doctor +wip --json status +``` + +Do not stash, reset, clean, delete state, or force-update a lane ref during +recovery. Common actions are: + +- `LANE_NOT_ACTIVE`: run `wip init`, or load the exact lane identity. +- `PATH_LEASE_CONFLICT`: select disjoint paths or wait for the owner to release + its lease. +- `SOURCE_INDEX_MOVED`: inspect the selected staged paths and rerun the complete + plan. +- `LOCK_TIMEOUT`: inspect active lanes, wait for the current operation, and + retry. +- `ref_updated: true`: preserve `plan_id` and `plan_digest`, then run the exact + `wip reconcile` command. + +[The error and recovery guide](docs/ERRORS.md) lists every typed code and its +required action. [SUPPORT.md](SUPPORT.md) explains what evidence is safe to +include in a report. + ## Safety scope `wip` protects coordination between cooperating local processes. It does not @@ -355,6 +428,7 @@ changes. These procedures do not authorize a push or release tag. Project authority and succession are in [GOVERNANCE.md](GOVERNANCE.md). Current support and safe incident-reporting guidance are in [SUPPORT.md](SUPPORT.md). Security reports use [SECURITY.md](SECURITY.md). +Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). The [open source practice guide](docs/OSS-PRACTICE-GUIDE.md) maps official guidance to project rules and records when maintainers must review it again. Local self-hosting receipts and safe-failure results are in diff --git a/SUPPORT.md b/SUPPORT.md index 14e6813..712407a 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -19,9 +19,10 @@ credentials in a report. For a security issue, follow [SECURITY.md](SECURITY.md). Do not report a suspected vulnerability in a public issue. -A confidential conduct-reporting channel is not configured in this local -checkout. The public-beta plan requires the owner to configure that channel and -approve a Code of Conduct before the project solicits public contributions. +Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Use +the repository host's private reporting form on the Security tab for a +confidential conduct report. Start the title with `Code of Conduct:`. Do not +put a conduct report in a public issue. ## Report a capture problem diff --git a/docs/OSS-PUBLIC-BETA.requirements.yaml b/docs/OSS-PUBLIC-BETA.requirements.yaml index 74d285f..f906960 100644 --- a/docs/OSS-PUBLIC-BETA.requirements.yaml +++ b/docs/OSS-PUBLIC-BETA.requirements.yaml @@ -326,7 +326,8 @@ "human_gate": true, "acceptance": "Before public contributions are solicited, the owner approves a Code of Conduct, names its enforcement responsibility, and configures a confidential conduct-reporting path.", "evidence": [ - {"kind": "gap", "value": "No approved Code of Conduct or confidential conduct-reporting channel exists in this local checkout.", "observed_on": "2026-08-16"} + {"kind": "configuration", "value": "GitHub private vulnerability reporting is enabled and supplies the confidential repository channel named in SUPPORT.md and the proposed Code of Conduct.", "observed_on": "2026-08-17"}, + {"kind": "human-gate", "value": "CODE_OF_CONDUCT.md names the repository owner as moderator and adapts Contributor Covenant 3.0. Owner review and merge remain required before contributions are solicited.", "observed_on": "2026-08-17"} ] }, { diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..4d70c13 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,18 @@ +# Commit plan examples + +The files in this directory show the JSON shape for a commit plan. Pass an +edited file with `wip commit --plan `. These files are templates, not +commands to run unchanged. + +Before you use an example: + +1. Replace every path with a staged path in the active lane's lease. +2. Replace every message with a concrete Conventional Commit subject. +3. Replace each verification command with a bounded command for the candidate + tree. +4. Run `wip plan` and compare its path groups with the edited file. +5. Run `wip commit --plan `. + +The command rejects paths outside the lease, duplicate files, vague messages, +and verification commands that fail or time out. It leaves the source `HEAD` +and complete index unchanged. diff --git a/examples/shared-split-plan.json b/examples/shared-split-plan.json new file mode 100644 index 0000000..41da09d --- /dev/null +++ b/examples/shared-split-plan.json @@ -0,0 +1,24 @@ +[ + { + "message": "fix(parser): preserve source error locations", + "files": [ + "internal/parser" + ], + "verify": [ + { + "argv": [ + "go", + "test", + "./internal/parser" + ], + "timeout_ms": 120000 + } + ] + }, + { + "message": "docs(parser): explain source error locations", + "files": [ + "docs/parser.md" + ] + } +]