open-code-review-toolkit 0.1.0__tar.gz → 0.2.0__tar.gz

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.2.0 - 2026-07-21
+
+### Features
+
+- Target Open Code Review 1.7.14 in preflight validation and the checksum-pinned GitLab CI example. ([#11](https://github.com/xeonvs/open-code-review-toolkit/issues/11))
+- Replace the ambiguous `/ocr keep` and `/ocr skip` discussion replies with `/ocr resolve` and `/ocr suppress`, preserve human-owned deduplication, and document the complete GitLab review lifecycle for developers and CI operators. ([#8](https://github.com/xeonvs/open-code-review-toolkit/issues/8))
+
+### Bug fixes
+
+- Allow stable release verification to coexist with previously published development builds of the same base version on TestPyPI. ([#10](https://github.com/xeonvs/open-code-review-toolkit/issues/10))
+- Treat ordinary merged pull requests as a successful no-op in the production release workflow while keeping release-branch authorization fail-closed. ([#7](https://github.com/xeonvs/open-code-review-toolkit/issues/7))
+
+### Security
+
+- Mark every source-distribution smoke install as hash-required while retaining the no-dependency boundary, and document the single-maintainer security posture and Scorecard triage policy. ([#6](https://github.com/xeonvs/open-code-review-toolkit/issues/6))
+
+### Documentation
+
+- Reduce the routine Ubuntu CI matrix to the supported Python 3.10 and 3.14 endpoints, matching the macOS matrix. ([#10](https://github.com/xeonvs/open-code-review-toolkit/issues/10))
+- Document accepted project decisions, their optional `ocr-accept` marker convention, and the guard that prevents a merge request from whitelisting its own findings. ([#11](https://github.com/xeonvs/open-code-review-toolkit/issues/11))
+
+
 ## 0.1.0 - 2026-07-20
 
 ### Features

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Unofficial GitLab CI integration layer for Open Code Review
 Project-URL: Homepage, https://github.com/xeonvs/open-code-review-toolkit
 Project-URL: Repository, https://github.com/xeonvs/open-code-review-toolkit
@@ -243,11 +243,19 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.7.13`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.7.14`. CI should pin the release and verify its published checksum before execution.
 Review output defaults to English. Set `OCR_REVIEW_LANGUAGE=Russian` to use Russian consistently in both OCR configuration and generated review context.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
+## How reviews evolve
+
+On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` to keep a discussion open without future repeats, or `/ocr resolve` to suppress it and resolve the discussion after the next successful posting transaction.
+
+Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
+
+Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the context generator supplies them to OCR only when the current merge request is not changing that file. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
+
 ## GitLab CI quick start
 
 1. Configure protected/masked `GITLAB_API_TOKEN` and LLM variables in GitLab.
@@ -264,7 +272,7 @@ ocr-ci context --output .review-context/dependencies.md
 ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log
 ```
 
-See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml) and the [GitLab guide](docs/gitlab.md).
+See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml), the [GitLab setup guide](docs/gitlab.md), and [GitLab review operations](docs/operations.md).
 
 ## Configuration and safety
 

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/README.md

@@ -15,11 +15,19 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.7.13`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.7.14`. CI should pin the release and verify its published checksum before execution.
 Review output defaults to English. Set `OCR_REVIEW_LANGUAGE=Russian` to use Russian consistently in both OCR configuration and generated review context.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
+## How reviews evolve
+
+On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` to keep a discussion open without future repeats, or `/ocr resolve` to suppress it and resolve the discussion after the next successful posting transaction.
+
+Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
+
+Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the context generator supplies them to OCR only when the current merge request is not changing that file. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
+
 ## GitLab CI quick start
 
 1. Configure protected/masked `GITLAB_API_TOKEN` and LLM variables in GitLab.
@@ -36,7 +44,7 @@ ocr-ci context --output .review-context/dependencies.md
 ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log
 ```
 
-See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml) and the [GitLab guide](docs/gitlab.md).
+See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml), the [GitLab setup guide](docs/gitlab.md), and [GitLab review operations](docs/operations.md).
 
 ## Configuration and safety
 

open_code_review_toolkit-0.2.0/changelog.d/README.md

@@ -0,0 +1,3 @@
+# Changelog fragments
+
+Every user-visible 0.x change needs one fragment named `<issue>.<type>.md`, where type is `feature`, `bugfix`, `security`, or `doc`. Use a numeric GitHub issue or pull-request identifier so generated links remain valid.

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/codex/AGENT_EXECUTION_PITFALLS.md

@@ -1,5 +1,21 @@
 # Agent Execution Pitfalls
 
+## Closing a public-contract change after only the feature merge
+
+**Failure mode:** A feature changes a public command or integration contract, its pull request merges, and a TestPyPI `.devN` build succeeds. The plan is then marked completed even though stable PyPI users still receive the old behavior.
+
+**Why it happens:** Implementation, preview publication, and stable delivery are treated as separate mental tasks even when the user asked for one outcome. SCM-derived versions also make the source tree appear ready for the next version without proving that a stable tag or package exists.
+
+**Required prevention:**
+
+1. Classify the work at plan start and write the target stable version into `PLANS.md`.
+2. Treat feature merge and TestPyPI `.devN` verification as intermediate receipts.
+3. When release is required, prepare the version/changelog release PR immediately after the development build is verified.
+4. Keep the objective active until the release workflow publishes and independent readback confirms PyPI, TestPyPI, the signed tag, immutable GitHub Release, hashes, attestations, and supported-Python installs.
+5. If publication is intentionally deferred, record who deferred it, why, and the exact command or PR needed to resume.
+
+**Closure question:** "Can a user installing from production PyPI obtain the promised behavior now?" If not, the stable-release objective is not complete.
+
 This note records recurring execution mistake patterns discovered during real work. Record generalized lessons, not one-off complaints.
 
 ## Planning And Context Discipline

open_code_review_toolkit-0.2.0/docs/codex/TASKS_BACKLOG.md

@@ -0,0 +1,87 @@
+# Tasks Backlog
+
+This file tracks future work that is not active. Active extraction work is owned by `PLANS.md`.
+
+## Backlog Item: Native fuzzing campaign
+
+Status: parked
+Priority: medium
+
+### Activation Trigger
+
+- A supported Python fuzzing backend is selected with reproducible local execution, bounded CI resources, and corpus ownership.
+
+### Goal
+
+Fuzz the untrusted-input boundaries with meaningful targets for result normalization, context rendering, GitLab payload parsing, and registry metadata validation. Integrate a public fuzzing service only after the targets demonstrate useful coverage and stable crash minimization.
+
+### Next Safe Action
+
+1. Compare Atheris with property-based alternatives across Python 3.10-3.14 and design a small synthetic seed corpus without adding a runtime dependency.
+
+### Exit Criteria
+
+- Native targets run locally and in bounded CI, retain minimized synthetic regressions, publish no repository or provider secrets, and are recognized by the selected fuzzing service.
+
+## Backlog Item: OpenSSF Best Practices registration
+
+Status: owner action
+Priority: low
+
+### Activation Trigger
+
+- The owner is ready to authenticate at `bestpractices.dev` and attest every passing-level criterion truthfully.
+
+### Goal
+
+Register the public repository for an OpenSSF Best Practices badge without guessing owner-only governance or project-usage answers.
+
+### Next Safe Action
+
+1. Complete the passing-level questionnaire with evidence links to the public repository and leave unsupported criteria unmet.
+
+### Exit Criteria
+
+- The public badge record exists, all answers have current evidence, and the README displays only the earned status.
+
+## Backlog Item: Additional provider adapters
+
+Status: parked
+Priority: low
+
+### Activation Trigger
+
+- A provider-neutral core has shipped and a concrete provider integration has an owner and testable API contract.
+
+### Goal
+
+Add another code-hosting adapter without weakening the provider-neutral core or GitLab behavior.
+
+### Next Safe Action
+
+1. Write an adapter contract proposal based on the shipped GitLab boundary and validate it against synthetic fixtures.
+
+### Exit Criteria
+
+- The new adapter has isolated tests, documentation, and no provider-specific leakage into core modules.
+
+## Backlog Item: File-based user configuration
+
+Status: parked
+Priority: low
+
+### Activation Trigger
+
+- Environment-only configuration becomes a demonstrated usability constraint after v0.1.
+
+### Goal
+
+Evaluate a versioned user configuration file without silently changing environment precedence or secret handling.
+
+### Next Safe Action
+
+1. Draft a schema and threat model; do not implement until compatibility and migration behavior are agreed.
+
+### Exit Criteria
+
+- Schema, precedence, migration, secret handling, and validation behavior are documented and tested.

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/configuration.md

@@ -41,4 +41,27 @@ Posting requires `GITLAB_API_TOKEN`, `CI_SERVER_URL`, `CI_PROJECT_ID`, and `CI_M
 
 The `OCR_CONTEXT_*` family bounds files, bytes, changed paths, instructions, manifest content, dependency output, and generated background size. `OCR_BACKGROUND_MAX_CHARS` defaults to and is capped at `7950`; `OCR_BACKGROUND_MAX_BYTES` independently enforces the UTF-8 byte budget. The default output is `.review-context/dependencies.md`. The generator rejects symlink escapes and prunes common vendor/build directories.
 
+### Accepted project decisions
+
+Use `.opencodereview/accepted-decisions.md` for a reviewed, project-wide decision that OCR would otherwise report repeatedly. Each entry should have a stable slug, a concise rationale, an explicit scope, and an inline marker that ties the decision to the relevant code or configuration:
+
+```markdown
+## generated-client-timeout
+
+The generated client keeps the provider's 90-second timeout so regenerated
+code remains reproducible. Do not report that timeout in `src/client/generated.py`.
+
+Look for `# ocr-accept: generated-client-timeout` at the configured value.
+```
+
+```python
+REQUEST_TIMEOUT = 90  # ocr-accept: generated-client-timeout
+```
+
+`ocr-accept` is a human-readable convention, not a source-code parser or blanket linter suppression. The complete, byte-bounded Markdown file is sanitized, redacted, and included under `Accepted project decisions` in the generated review background; OCR is instructed not to raise matching findings. Keep the rationale narrow and name the affected paths or behavior so unrelated findings remain reviewable.
+
+The decision file must already exist on the target branch and pass normal review. If the current merge request changes `.opencodereview/accepted-decisions.md`, or changed-file discovery fails, the toolkit omits all accepted decisions for that run to prevent self-whitelisting. A decision reduces repeated model findings but is not a deterministic static-analysis exemption: reviewers should still use `/ocr suppress` or `/ocr resolve` for a concrete GitLab discussion, and should update or remove stale decisions when the underlying tradeoff changes.
+
+Use the default `OCR_POST_MODE=draft` for normal CI so all current notes are created as drafts before they are published and replaceable notes from the previous run are removed. Draft publication is sequential rather than atomic; the previous review is preserved unless every current draft publishes. Set `OCR_STRICT_POSTING=true` when the review job is a required merge gate; keep the default `false` only for advisory pipelines where GitLab posting availability must not block the pipeline. Reviewer commands and the complete repeated-run contract are documented in [GitLab review operations](operations.md).
+
 Run `ocr-ci --help` and each subcommand's help for command arguments. Secret values are redacted from operational error text.

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/engineering/project_principles.md

@@ -14,6 +14,10 @@ This is the short index of stable cross-cutting engineering rules for Open Code
 8. Use coherent production-quality slices when work must be decomposed; do not leave placeholder architecture as a milestone.
 9. Require changelog fragments for user-visible 0.1.x changes and SCM tags for versions.
 10. Treat TestPyPI as public disclosure and preserve the manual privacy/license gate before publishing.
+11. Treat automated security scores as evidence to classify, not targets to game; remediate concrete repository-owned risk and document temporal or governance constraints truthfully.
+12. Version public behavior deliberately. An incompatible pre-1.0 contract change may select the next minor version, but it is not delivered to stable users until the versioned package and release artifacts are published and independently verified.
+13. Keep implementation and release as one traceable objective whenever stable publication is requested or required. Feature validation proves readiness; registry and GitHub readback prove delivery.
+14. A deferral is a blocked or pending release state, not successful closure. Preserve the exact continuation point so a later agent does not infer that a development build satisfied a stable-release promise.
 
 ## Documentation Ownership
 
@@ -22,5 +26,5 @@ This is the short index of stable cross-cutting engineering rules for Open Code
 - `docs/gitlab.md` owns GitLab installation and operating guidance.
 - `docs/security.md` owns the runtime trust model; `SECURITY.md` owns vulnerability reporting.
 - `docs/development.md` owns local contributor commands.
-- `docs/release.md` owns the release and disclosure process.
+- `docs/release.md` owns release classification, delivery, and disclosure.
 - `AGENTS.md`, `PLANS.md`, and `docs/codex/` own agent workflow rather than product behavior.

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/gitlab.md

@@ -4,7 +4,7 @@ The toolkit's first provider adapter posts review results to GitLab merge reques
 
 ## Installation
 
-Install `open-code-review-toolkit` from PyPI. The example obtains the expected toolkit wheel digest from the matching immutable GitHub Release, then uses pip hash-checking and a local install. Install Open Code Review separately and pin `v1.7.13`; verify the release checksum before making the binary executable. The package never downloads OCR.
+Install `open-code-review-toolkit` from PyPI. The example obtains the expected toolkit wheel digest from the matching immutable GitHub Release, then uses pip hash-checking and a local install. Install Open Code Review separately and pin `v1.7.14`; verify the release checksum before making the binary executable. The package never downloads OCR.
 
 Copy and adapt [the synthetic CI example](../examples/gitlab/ocr-review.gitlab-ci.yml). Keep the lint stage before the AI review stage so failed project checks block review. The example downloads a pinned toolkit wheel with bounded retries/timeouts, verifies its SHA-256 before a local `--no-deps` install, generates one background file, and passes it once with `--background-file`.
 
@@ -22,6 +22,10 @@ Store secrets as masked, protected CI variables. Do not place them in YAML, comm
 
 `ocr-ci preflight` validates the installed OCR version, GitLab access, and configured LLM model. `configure` and `context` resolve the same `OCR_REVIEW_LANGUAGE` value, so the OCR system prompt and review background cannot disagree. `configure` and `mcp-config` write OCR configuration without invoking a config subprocess. `context` creates bounded Markdown. `post` interprets a JSON artifact and publishes bounded notes with rollback and ownership safeguards.
 
+Repeated reviews have a reviewer-controlled lifecycle rather than appending the same notes indefinitely. Untouched OCR-only notes are replaced after a successful run, human-touched discussions are preserved, and `/ocr suppress` or `/ocr resolve` controls future matching findings. Read [GitLab review operations](operations.md) for the complete state machine, deduplication boundaries, posting modes, permissions, limits, and failure semantics.
+
+For a deliberate project-wide tradeoff that should be supplied to every review, add a narrowly scoped entry to `.opencodereview/accepted-decisions.md` in an earlier reviewed merge request. The [configuration reference](configuration.md#accepted-project-decisions) documents its `ocr-accept` marker convention, prompt-level semantics, and self-whitelisting guard.
+
 OCR is configured through its `openai-responses` provider. Optional stdio bridge tools are supplied with `OCR_MCP_SERVERS_JSON`; treat every configured MCP command as privileged code.
 
 Use merge-request source and base SHAs, not a merge-result commit, when choosing the reviewed range. Keep the self-test job manual. See [docs/security.md](security.md) for trust boundaries and [docs/configuration.md](configuration.md) for every input.

open_code_review_toolkit-0.2.0/docs/operations.md

@@ -0,0 +1,83 @@
+# GitLab review operations
+
+This guide is for developers and CI operators who connect Open Code Review Toolkit to a GitLab merge-request pipeline and need to understand what happens after the first review. Installation remains in [gitlab.md](gitlab.md); the complete environment contract is in [configuration.md](configuration.md).
+
+## What one review run publishes
+
+The toolkit reads the previous OCR-owned notes and discussions before it writes anything. It fingerprints new findings, removes findings already owned or suppressed by reviewers, and publishes:
+
+- inline GitLab discussions when a finding has a valid diff position;
+- bounded fallback notes when GitLab cannot accept a position, for example after relevant lines moved outside the current diff;
+- one summary note with counts, warnings, omitted findings, review effort, reviewed commit identity, and available token/tool usage.
+
+`OCR_MAX_POST_COMMENTS` limits individually published findings. The default is 50 and the hard limit is 200. Omitted findings are counted in the summary rather than silently disappearing.
+
+## Discussion lifecycle
+
+```mermaid
+flowchart LR
+    finding[OCR finding] --> position{Valid diff position?}
+    position -- No --> fallback[Fallback MR note]
+    position -- Yes --> open[Open OCR discussion]
+
+    open --> action{Reviewer action before rerun}
+    action -- No action --> replace[Replace after successful rerun]
+    replace --> open
+    action -- Human reply --> owned[Human-owned and suppressed]
+    action -- Resolve in GitLab --> resolved[Resolved and suppressed]
+    action -- OCR command --> command{Command}
+    command -- suppress --> suppressed[Open and suppressed]
+    command -- resolve --> pending[Resolve requested]
+    pending -- Publish succeeds --> resolved
+```
+
+If posting fails, the transition does not complete: the previous review and every human-owned, suppressed, or resolve-requested discussion keep their prior state. Matching findings remain suppressed on later runs.
+
+An untouched open OCR discussion is bot-owned. A successful rerun replaces bot-owned notes with the current review instead of accumulating stale copies. Once a person replies, the discussion becomes human-owned: the toolkit preserves the complete conversation and suppresses a finding at the recorded inline position or with a compatible fingerprint.
+
+A discussion resolved with GitLab's normal Resolve action is also preserved and suppresses a matching future finding. The toolkit never reopens a discussion.
+
+## Reviewer commands
+
+Reply inside an OCR-created discussion with exactly one command. Commands are case-insensitive, but the whole reply must contain only the command and optional surrounding whitespace. A command inside prose or a code block is ignored. If reviewers post several recognized commands, the newest one wins. Bot and GitLab system notes cannot issue commands.
+
+| Command | Discussion after the command | Matching finding on future runs |
+| --- | --- | --- |
+| `/ocr suppress` | Remains open | Suppressed |
+| `/ocr resolve` | Resolved after the next successful posting transaction | Suppressed |
+| Ordinary human reply | Remains in its current state and becomes human-owned | Matching position or fingerprint suppressed |
+| GitLab Resolve action | Resolved | Suppressed |
+
+The command is applied when the next pipeline reads the discussion. `/ocr resolve` waits until all notes created for the current review have published successfully before resolving the old discussion. A failed run therefore does not close it prematurely.
+
+`/ocr keep` and `/ocr skip` were removed in 0.2.0 and are not aliases. An existing reply containing an old command still counts as an ordinary human reply: its conversation is preserved and matching future findings remain suppressed, but it does not request automatic resolution.
+
+## Will OCR report the same bug again?
+
+Every OCR note contains an invisible toolkit marker and a stable finding fingerprint. The current fingerprint combines the repository path, normalized finding text, and the existing-code fragment when OCR supplies one. This lets suppression survive an ordinary line shift. Backward-compatible fingerprints keep review decisions made by earlier toolkit versions usable.
+
+Suppression checks both the recorded inline position and compatible fingerprints. A new finding anchored to the same recorded path and line is suppressed even if its text changes; elsewhere, the fingerprint prevents ordinary line movement from bypassing the decision. Suppression is intentionally not a permanent rule for an entire file: a materially different explanation, code fragment, path, or duplicate occurrence at another location can become a new finding and receive a new discussion. When identical findings occur more than once, occurrence-aware fingerprints prevent suppressing every occurrence after a reviewer acts on only one of them.
+
+## Posting modes and blocking behavior
+
+`OCR_POST_MODE=draft` is the safe default. The toolkit creates this run's notes as GitLab draft notes, publishes only those drafts one by one, and removes replaceable notes from the previous successful review only after every publish succeeds. If creation fails, drafts from the current attempt are removed and the previous review remains visible. Draft mode avoids exposing an incomplete review during the creation phase, but GitLab does not provide an atomic bulk-publish transaction.
+
+`OCR_POST_MODE=direct` writes notes immediately. It exists as an emergency compatibility override. The toolkit still performs best-effort rollback, but an ambiguous network timeout can mean GitLab accepted a write that the runner cannot confirm. Prefer `draft` for normal CI.
+
+`OCR_STRICT_POSTING=false` is the advisory default: an OCR or posting error remains visible in the job log and, when possible, in an MR note, but the posting helper exits successfully. Set `OCR_STRICT_POSTING=true` when OCR review is a required merge gate so OCR failures, an unavailable GitLab API, an unsafe previous-state snapshot, an invalid OCR result, or failed publication make the job fail.
+
+## GitLab identity and permissions
+
+Use a dedicated project access token with `api` scope and at least the Developer role. Store it in `GITLAB_API_TOKEN`. The toolkit needs to read merge-request notes, discussions, diff refs, and the current token identity; create and delete its own notes or drafts; publish drafts; and resolve discussions requested by reviewers.
+
+The toolkit calls `GET /user` before posting and refuses to write if it cannot identify the token owner. It treats a note as bot-owned only when both the invisible OCR marker and the actual GitLab author ID match. Text that merely imitates an OCR marker is not enough to claim or delete another user's note.
+
+## Reruns, failures, and fallback notes
+
+Before a rerun, the toolkit takes a bounded snapshot of OCR-owned notes, discussions, and drafts. If it cannot collect that state reliably, it refuses to publish a replacement so resolved, suppressed, and human-owned decisions are not lost. Reads and writes have bounded response sizes and timeouts; writes are retried only when retrying is safe.
+
+The previous review is deleted only after the new review has been created and, in draft mode, published. A definite write failure rolls back notes known to belong to the current attempt. An ambiguous draft-publish failure does not delete possibly published notes because the runner cannot prove which writes GitLab accepted.
+
+When GitLab rejects an inline position as invalid, the toolkit moves that finding into one or more bounded fallback notes. Ambiguous write failures do not use fallback, because doing so could duplicate a discussion that GitLab already accepted.
+
+Source and base merge-request SHAs define the reviewed range. A merge-result commit is not treated as the source branch head. The summary records the reviewed SHA and warns when the current MR head has moved, so reviewers can distinguish a current review from a stale pipeline result.

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/release.md

@@ -1,10 +1,25 @@
 # Releases
 
-Production versions come from SCM tags through hatch-vcs. The tracked `.release-version` and `.release-source-date-epoch` files authorize one reproducible stable build, while `.next-version` defines the next TestPyPI development line. Public interfaces may evolve before 1.0, but every user-visible 0.1.x change still requires a Towncrier fragment.
+Production versions come from SCM tags through hatch-vcs. The tracked `.release-version` and `.release-source-date-epoch` files authorize one reproducible stable build, while `.next-version` defines the next TestPyPI development line. Public interfaces may evolve before 1.0, but every user-visible 0.x change still requires a Towncrier fragment.
+
+## Release-required changes
+
+A change is release-required when it removes or incompatibly changes a public CLI, environment variable, generated schema, reviewer command, or documented integration behavior, or when the user explicitly requests stable publication. Select the target version before implementation closure and keep one active plan through both development and release delivery. Other user-visible fixes and features must still be classified explicitly; they are not automatically entitled to a stable release after every merge.
+
+The delivery sequence is:
+
+1. merge the feature through protected `main`;
+2. verify the deterministic `.devN` wheel and sdist on TestPyPI;
+3. prepare a signed `release/vX.Y.Z` pull request containing the stable version marker, deterministic epoch, generated Towncrier changelog, and next development line;
+4. use release-PR merge as the human authorization gate;
+5. monitor TestPyPI stable publication, production PyPI publication, signed tag, provenance, and immutable GitHub Release;
+6. independently compare artifact hashes and smoke-install the wheel on Python 3.10 and the sdist on Python 3.14.
+
+Do not mark the objective complete after step 1 or 2. If the owner explicitly defers stable publication, record the target version and exact resume point in `PLANS.md`.
 
 ## Development builds
 
-Every non-release push to protected `main` runs the **TestPyPI development build** workflow. The immutable workflow run number produces `0.2.0.devN`; rerunning the same run reuses the version and succeeds only when the already-published filenames and SHA-256 values match the reviewed artifacts. The workflow uses TestPyPI Trusted Publishing, publishes attestations, verifies bounded HTTPS downloads, and smoke-installs the exact wheel and sdist locally with `--no-deps`.
+Every non-release push to protected `main` runs the **TestPyPI development build** workflow. The immutable workflow run number produces `<next-version>.devN` (for example `0.3.0.devN` after the 0.2.0 release); rerunning the same run reuses the version and succeeds only when the already-published filenames and SHA-256 values match the reviewed artifacts. The workflow uses TestPyPI Trusted Publishing, publishes attestations, verifies bounded HTTPS downloads, and smoke-installs the exact wheel and sdist locally with `--no-deps`.
 
 Development builds never create tags or GitHub Releases and never publish to production PyPI. TestPyPI is public disclosure, so only reviewed pull requests may reach `main`.
 

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/docs/security.md

@@ -18,6 +18,12 @@ The toolkit bridges four trust domains: repository content, OCR and its LLM/MCP
 
 Use a dedicated bot identity and least-privilege `GITLAB_API_TOKEN`. Protect and mask credentials. Do not expose secrets to pipelines for untrusted forks. Begin with manual execution for trusted contributors, review generated notes, and enable automatic posting only after the repository's threat model is accepted.
 
-Pin Open Code Review `v1.7.13` and verify its checksum. Pin Python dependencies through `uv.lock` and GitHub Actions by immutable commit SHA. MCP servers are privileged child processes; allow only reviewed commands and tools.
+Pin Open Code Review `v1.7.14` and verify its checksum. Pin Python dependencies through `uv.lock` and GitHub Actions by immutable commit SHA. MCP servers are privileged child processes; allow only reviewed commands and tools.
+
+## Repository security posture
+
+Protected `main` requires pull requests, signed commits, a current branch, resolved review threads, and the complete CI, package-build, dependency, secret, and CodeQL check set. The project currently has one maintainer, so it cannot truthfully require an independent human approval for maintainer-authored changes. This is an explicit residual risk: automated review does not replace a second human. External contributions still receive maintainer review, and independent approval will become mandatory when a second active maintainer can provide it without blocking security fixes.
+
+OpenSSF Scorecard findings are interpreted as supply-chain posture signals rather than vulnerability reports. Repository-age and historical-coverage checks improve only with time and repeated runs; badge registration requires owner attestations; a useful fuzzing integration requires native fuzz targets and infrastructure rather than a workflow added only to satisfy a scanner. Actionable repository-owned findings are fixed through normal signed pull requests.
 
 The detailed environment contract is in [configuration.md](configuration.md). Vulnerability reporting is in [SECURITY.md](../SECURITY.md).

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/examples/gitlab/ocr-review.gitlab-ci.yml

@@ -6,10 +6,12 @@ default:
   image: python:3.12-slim
 
 variables:
-  OCR_VERSION: "v1.7.13"
+  OCR_VERSION: "v1.7.14"
   OCR_TOOLKIT_VERSION: "0.1.0"
   OCR_TOOLKIT_CHECKSUMS_URL: "https://github.com/xeonvs/open-code-review-toolkit/releases/download/v0.1.0/SHA256SUMS"
-  OCR_SHA256: "4f0d8cf68b59c7e3573fa8312779401aa48ee498733fb59245eb664791a09c20"
+  OCR_SHA256: "f5ee3118b72fe702c94457aa466ebad82b8d4bf6ced6e0347534f4cfdbcc5f8b"
+  OCR_POST_MODE: "draft"
+  OCR_STRICT_POSTING: "true"
   OCR_LLM_VALIDATE_MODEL: "false"
   OCR_LLM_ALLOWED_MODELS: ""
   OCR_RUN_HELPER_TESTS: "false"

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/pyproject.toml

@@ -75,7 +75,7 @@ include = [
 ]
 
 [tool.hatch.version.raw-options]
-fallback_version = "0.2.0.dev0"
+fallback_version = "0.3.0.dev0"
 
 [tool.ruff]
 target-version = "py310"

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/src/ocr_toolkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/src/ocr_toolkit/posting/formatting.py

@@ -234,7 +234,7 @@ def format_omitted_comments_summary(
 
     return (
         "**Open Code Review omitted comments**\n\n"
-        f"After reviewer skip filters, Open Code Review has "
+        f"After reviewer suppression filters, Open Code Review has "
         f"{publishable_total} publishable comment(s). This CI job publishes "
         f"at most {publish_limit} comment(s) per run. The remaining {omitted} "
         "comment(s) were "

{open_code_review_toolkit-0.1.0 → open_code_review_toolkit-0.2.0}/src/ocr_toolkit/posting/markers.py

@@ -19,7 +19,9 @@ MARKER_WITH_FINGERPRINT_RE = re.compile(
 )
 
 
-OCR_REPLY_COMMAND_RE = re.compile(r"(?i)\A[ \t]*/ocr[ \t]+(skip|keep)[ \t]*(?:\r?\n[ \t]*)*\Z")
+OCR_REPLY_COMMAND_RE = re.compile(
+    r"(?i)\A[ \t]*/ocr[ \t]+(suppress|resolve)[ \t]*(?:\r?\n[ \t]*)*\Z"
+)
 
 
 FINGERPRINT_LEN = 32  # hex characters (= 16 raw bytes from blake2b)
@@ -94,7 +96,7 @@ def comment_fingerprint(comment: dict[str, Any]) -> str | None:
 
     The hash combines path, normalized review text, and the commented code
     fragment (`existing_code`) when OCR provides it. It omits the anchor line
-    only when that code anchor exists, so resolved findings and `/ocr skip`
+    only when that code anchor exists, so resolved findings and `/ocr suppress`
     survive ordinary line shifts without broadening generic no-code comments
     across a whole file. Returns None for comments missing a usable path.
 
@@ -162,8 +164,8 @@ def legacy_comment_fingerprint(comment: dict[str, Any]) -> str | None:
     """Return the pre-migration 16-hex fingerprint for one OCR finding.
 
     Why: markers produced before the 8→16 byte digest migration are still
-    stored in resolved/skip-flagged threads. Without this companion,
-    `/ocr skip` decisions made under the old length would silently stop
+    stored in resolved or suppressed discussions. Without this companion,
+    `/ocr suppress` decisions made under the old length would silently stop
     suppressing their findings after the migration. Same line-based
     payload as the previous fingerprint implementation, narrower digest.
     """
@@ -180,7 +182,7 @@ def comment_fingerprint_candidates(comment: dict[str, Any]) -> set[str]:
     annotated = comment.get("_ocr_fingerprint")
     if isinstance(annotated, str) and annotated:
         # For duplicate findings, the annotated marker is the current run's
-        # identity. Do not also include the base hash: a skip on the first
+        # identity. Do not also include the base hash: suppressing the first
         # duplicate would suppress every later duplicate in the same file.
         candidates = {annotated}
         if line_number(comment.get("start_line") or comment.get("line")) > 0:
@@ -249,8 +251,8 @@ def is_diff_note(note: dict[str, Any]) -> bool:
 
     Such notes are owned by the /discussions cycle and must NOT be
     deleted via DELETE /notes/{id}, otherwise a reviewer-preserved
-    thread (resolved, /ocr skip, /ocr keep) gets destroyed despite our
-    decision to keep it.
+    thread (resolved, /ocr suppress, /ocr resolve) gets destroyed despite our
+    decision to preserve it.
     """
 
     if note.get("type") == "DiffNote":