ScopeLint

ScopeLint checks every pull request against your contract, automatically. It catches scope creep where it actually happens, in the code, before it becomes unbillable work.

Comment

Inspiration

Consulting and agency teams operate on a fragile assumption: that scope stays where the contract says it should. In practice, scope creep doesn't announce itself in a meeting, it slips in through a pull request, an "extra" feature added mid-sprint that nobody flags until it's already built and unbillable. Every existing scope-monitoring tool watches conversations, tasks, and emails. None of them watch the one place the actual, billable work materializes: the code itself. That gap is ScopeLint.

What it does

ScopeLint is a GitHub Action and CLI that checks every pull request against a project's statement of work, automatically, the same way tests and linters already run. Commit the contract as scope.md, and GPT-5.6 classifies each functional area of a pull request as in scope, out of scope, or gray area, citing the exact clause it matched. Out-of-scope work gets a client-ready change order draft attached on the spot. A running scope ledger tracks cumulative drift and estimated unbilled hours across the life of a project. A bundled replay mode with canned fixtures lets anyone try it with zero API key.

How we built it

Built solo, end to end, with Codex, staged deliberately across six phases: the offline CLI skeleton and replay mode, live GPT-5.6 classification with structured JSON output, GitHub Actions integration and PR-comment posting, the scope ledger, tests and documentation, and finally a full demo project, an Express loyalty API with a real statement of work and three staged pull requests, used for this submission's live evidence. The classifier runs on gpt-5.6-terra, chosen for its balance of structured reasoning and cost on a per-pull-request task.

Challenges we ran into

Real infrastructure friction, not algorithm design, ate most of the time: git authentication with a personal access token that needed the workflow scope before GitHub would accept a change to .github/workflows/, a Codex session that reported creating a file it hadn't actually written to disk (caught only when a live pull request check failed with a missing-key error), and pacing Codex's effort level up or down per stage to make $100 in credits last across all six build phases plus a full second demo repository.

Accomplishments that we're proud of

A working, live demo where every claim is verifiable, not staged screenshots. The three pull requests in the demo repository actually run ScopeLint through GitHub Actions, call GPT-5.6 live, and post real verdicts a judge can click into and inspect themselves, including the model correctly refusing to cite a contract clause when the scope document didn't actually contain one, rather than hallucinating a match. Shipping a full CLI, GitHub Action, ledger system, test suite, and a second demo repository with staged scenarios, solo, inside a single day's build window.

What we learned

That most of the risk in a build like this isn't the AI reasoning, it's the plumbing around it. GitHub Actions rejecting a workflow file over a missing token scope, git authentication breaking silently, an agent reporting success on a file it hadn't actually written, these cost more time than designing the classification prompt itself. We also learned to pace an AI coding agent's effort level deliberately: high reasoning for structurally complex stages like the GitHub Action and the demo repository, lower effort for templated work like documentation and tests, to make a fixed credit budget stretch across a full six-stage build.

What's next for ScopeLint

A hosted dashboard aggregating the scope ledger across every repo a consulting team manages, so a delivery lead sees drift trends across an entire client portfolio, not just one project. Direct integrations so an approved change order pushes straight into Jira or a billing tool instead of sitting in a pull request comment. Support for multiple scope documents per repo, for teams running several concurrent workstreams against one codebase.

Built With

  • codex
  • express-(demo-api)
  • github-actions
  • gpt-5.6-terra
  • node.js-20
  • the-openai-sdk
  • typescript
  • vitest
Share this project:

Updates