Carson4 spec

[wanghailei]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces the comprehensive specification for Carson 4.0, significantly expanding its repository governance capabilities. The core focus shifts to managing concurrent agent work within a single repository by establishing a clear "Integration Authority" for each governed repository. This authority dictates how worktrees are created, how changes are delivered, and how the repository maintains a consistent state, aiming to prevent common issues like stale bases and inconsistent landing paths. The specification details new configuration options, a dedicated command for managing authority, and authority-aware behavior for all major Carson operations, ensuring a robust and predictable workflow for developers.

Highlights

• Expanded Carson 4.0 Specification: The document docs/carson-4.0.md has been completely rewritten and expanded to detail the full Carson 4.0 product contract, moving beyond just worktree-first governance.
• Introduction of Integration Authority: A core new concept, "Integration Authority" (either remote or local), has been introduced to define how new work begins and how completed work rejoins shared truth in a governed repository.
• Updated Repository Configuration: The govern.repos configuration now supports specifying an authority (remote or local) per repository, with remote as the default and backward compatibility for legacy string entries.
• New carson repo authority Command: A new command carson repo authority <remote|local> has been added to safely change a repository's configured integration authority, with strict preconditions to prevent ambiguous states.
• Authority-Aware Command Semantics: Key Carson commands like sync, worktree create, deliver, status, audit, review, and govern have been updated to behave differently based on the repository's configured integration authority.
• Migration Contract Defined: Clear guidelines for safely migrating existing Carson 3.x configurations to Carson 4.0, ensuring backward compatibility and default behaviors.

Changelog

• docs/carson-4.0.md
  • Document restructured and expanded into a full product specification for Carson 4.0.
  • Introduced "Integration Authority" as a central concept, defining remote and local authority models.
  • Updated govern.repos configuration to support per-repository authority settings, including backward compatibility.
  • Added a new carson repo authority command for managing repository integration authority.
  • Detailed authority-aware semantics for carson onboard, carson sync, carson worktree create, carson deliver, carson status, carson audit, carson review gate, carson review sweep, and carson govern.
  • Replaced previous "Rules" (e.g., "Rule 1: worktree-first") with "Core Invariants" and comprehensive command contracts.
  • Defined "Platform Enforcement" and "Migration Contract" for safe adoption and transition.
  • Added "Acceptance Criteria" outlining blocking and allowing behaviors for Carson 4.0.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive specification for Carson 4.0, replacing the previous brief document. The new spec is well-structured and detailed, introducing the core concept of 'authority' (remote vs. local) and defining its impact across various commands. The changes significantly improve the clarity and completeness of the product definition. My review focuses on a few areas where the specification could be made more precise to ensure a deterministic implementation. Overall, this is an excellent and thorough update to the specification.

[gemini-code-assist]

The specification states that Carson "may auto-fix safe preconditions" before switching authority (also on line 223). This is ambiguous and could lead to unexpected behavior. To ensure predictability for implementers and users, please specify exactly which conditions are considered safe to auto-fix. For example, does this include stashing uncommitted changes? If no auto-fixes are planned, I recommend removing this statement.

[gemini-code-assist]

The condition "no in-flight local branches remain that would become ambiguous after the switch" is not specific enough. What defines an "ambiguous" branch in this context? The specification should clearly define this to ensure the check is implemented correctly. For example, an ambiguous branch could be defined as "any local branch that does not have a remote tracking branch and is not a Carson worktree branch". This is also referenced in the acceptance criteria on line 387.

[gemini-code-assist]

The condition for switching authority that "local and remote primary branches are aligned closely enough" is ambiguous. This could be interpreted in multiple ways (e.g., no divergence, within a certain number of commits). The specification should define this condition precisely to ensure a deterministic implementation. For example, does it mean "the local primary branch must be a fast-forward of the remote, or vice-versa, with no divergence"?