diff --git a/README.md b/README.md index 8973c32..4b73d7e 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,9 @@ node dist/index.js review --task "Fix header CSS styling" --old test/fixtures/sc Add this workflow to review whether a pull request stayed within its stated goal: +[Install TaskBound in advisory mode](docs/INSTALL.md) gives teams a +copy-paste workflow, first-PR guidance, and links for reporting real feedback. + ```yaml name: TaskBound diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..80ade5c --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,83 @@ +# Install TaskBound In Advisory Mode + +Use this path when you want to try TaskBound on a real repository without +blocking pull requests. The goal is to collect signal first: does the Action +flag real AI-agent scope creep, and what would make the report useful for your +team? + +## Copy-Paste Workflow + +Create `.github/workflows/taskbound.yml` in the repository you want to evaluate. + +```yaml +name: TaskBound + +on: + pull_request: + +permissions: + contents: read + +jobs: + scope-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - uses: Conalh/TaskBound@v0.2.1 + with: + fail-on: none +``` + +`fetch-depth: 0` lets TaskBound compare the pull request base and head commits. +`fail-on: none` keeps the first run advisory while you check the signal. + +The same workflow is available as +[`examples/taskbound-advisory.yml`](../examples/taskbound-advisory.yml). + +## First Pull Request + +Run the Action on one or two real pull requests that include AI-agent edits. +TaskBound uses the pull request title as the stated task and the pull request +body as additional scope context. + +Good first PR body scope looks like this: + +```markdown +Only touch `src/auth/session.ts` and related tests. +Do not change package scripts, CI workflows, or MCP configuration. +``` + +Start by reading the step summary and warning annotations. Do not raise +`fail-on` until the findings are trusted for your repository. + +## Report What You Learn + +Use real PRs, Action runs, or redacted notes when you report feedback: + +- False positive: [open a false-positive report](https://github.com/Conalh/TaskBound/issues/new?template=false-positive.yml) +- Missing signal: [open a missing-signal request](https://github.com/Conalh/TaskBound/issues/new?template=missing-signal.yml) +- Team workflow need: [open a team pilot request](https://github.com/Conalh/TaskBound/issues/new?template=team-pilot.yml) + +The paid-layer validation gate is tracked in +[issue #8](https://github.com/Conalh/TaskBound/issues/8). External installs and +team feedback count only when they are tied to real usage or a real install +attempt. The evidence rules are in the +[`docs/TEAM_VALIDATION_PLAYBOOK.md`](TEAM_VALIDATION_PLAYBOOK.md). + +## After Signal Improves + +Keep `fail-on: none` until your team agrees the report is useful. Then consider +raising the threshold: + +```yaml + - uses: Conalh/TaskBound@v0.2.1 + with: + fail-on: critical +``` + +For team-wide needs such as shared policy packs, org baselines, Slack or Jira +routing, saved reports, or reviewer assignment, use the team pilot template +instead of assuming a hosted product should be built first. diff --git a/examples/taskbound-advisory.yml b/examples/taskbound-advisory.yml new file mode 100644 index 0000000..9eebe76 --- /dev/null +++ b/examples/taskbound-advisory.yml @@ -0,0 +1,19 @@ +name: TaskBound + +on: + pull_request: + +permissions: + contents: read + +jobs: + scope-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - uses: Conalh/TaskBound@v0.2.1 + with: + fail-on: none diff --git a/test/adoption-docs.test.mjs b/test/adoption-docs.test.mjs new file mode 100644 index 0000000..6bba846 --- /dev/null +++ b/test/adoption-docs.test.mjs @@ -0,0 +1,27 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import test from 'node:test'; + +const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8')); +const actionRef = `Conalh/TaskBound@v${packageJson.version}`; + +test('adoption docs provide a copy-paste advisory Action install path', () => { + const readme = fs.readFileSync('README.md', 'utf8'); + const installGuide = fs.readFileSync('docs/INSTALL.md', 'utf8'); + const workflowExample = fs.readFileSync('examples/taskbound-advisory.yml', 'utf8'); + + assert.match(readme, /\[Install TaskBound in advisory mode\]\(docs\/INSTALL\.md\)/); + assert.match(installGuide, /## Copy-Paste Workflow/); + assert.match(installGuide, /## First Pull Request/); + assert.match(installGuide, /## Report What You Learn/); + assert.match(installGuide, /https:\/\/github\.com\/Conalh\/TaskBound\/issues\/8/); + assert.match(installGuide, /docs\/TEAM_VALIDATION_PLAYBOOK\.md/); + assert.match(installGuide, /fail-on: none/); + assert.match(installGuide, /fetch-depth: 0/); + assert.match(installGuide, /contents: read/); + assert.match(installGuide, new RegExp(actionRef.replaceAll('.', '\\.'))); + assert.match(workflowExample, new RegExp(actionRef.replaceAll('.', '\\.'))); + assert.match(workflowExample, /fail-on: none/); + assert.match(workflowExample, /fetch-depth: 0/); + assert.match(workflowExample, /contents: read/); +});