certainty-units 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nhan Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# certainty-units
+
+Free, open-source certainty scoring for project work items.
+Connects to **GitHub Issues, Linear, Jira, Notion** (Monday + ClickUp coming).
+Outputs a static HTML dashboard + Markdown report — zero server required.
+
+```
+npx certainty-units sync
+```
+
+Teams that track success by counting effort (points, tickets closed) see *how much* is moving —
+certainty-units shows *how sure you are* about what's moving, and what would make you surer.
+
+## Quick start
+
+Fastest path — score any public GitHub repo, no API key needed:
+
+```bash
+npx certainty-units init
+# edit certainty.config.yaml:
+#   source: github
+#   github:
+#     repo: your-org/your-repo
+npx certainty-units sync
+
+# Output: cu-report.html  (open in any browser)
+```
+
+For Linear / Jira / Notion, set the API key env var and run the same command:
+
+```bash
+LINEAR_API_KEY=lin_api_xxx npx certainty-units sync
+```
+
+Every sync prints instant insights in the terminal:
+
+```
+278 items  ·  avg certainty 56%
+  high 68  medium 116  low 54  uncertain 40
+
+Since last sync (2026-06-27):  avg 54% → 56%  ▲ +2  ·  12 new items
+  ▼ 45 → 20  ENG-142  Add SSO support
+  ▲ 30 → 80  ENG-98   Migrate billing
+
+Least certain open items:
+    5% #1099  always_allow permission policy not honored
+        missing: validation +40, workflow +20, discussion +15
+```
+
+## What it scores
+
+Each work item gets a **Certainty Score (0–100)**:
+
+| Signal | Max points | How it maps |
+|--------|-----------|-------------|
+| Validation status | 40 | `validated` → 40, `assumed` → 10 |
+| Workflow progress | 20 | `done` → 20, `review` → 15, `in_progress` → 10 |
+| Discussion | up to 15 | 5 pts per comment — undebated items hide risk |
+| Acceptance criteria | 10 | found on the item (see below) |
+| CU tier set | 10 | basic / intermediate / advanced |
+| Evidence / description | 5 | non-empty description |
+
+Scores map to levels: **high** (≥80) · **medium** (≥50) · **low** (≥20) · **uncertain** (<20)
+
+Every score is auditable: hover the score bar in the HTML report for the per-signal
+breakdown, and `cu-data.json` (via `--json`) includes `certainty_breakdown` per item.
+
+## Feed it real signals
+
+The score is only as honest as its inputs, so the adapters read signals your team
+already produces:
+
+- **Acceptance criteria** are detected automatically from an `## Acceptance Criteria`
+  heading (or `**Acceptance Criteria**`, or an `Acceptance criteria:` line) in the
+  item description, or from a markdown checklist (`- [ ] …`). In Notion, use an
+  `Acceptance Criteria` column.
+- **Validation labels** override workflow-derived validation. Label an item
+  `validated`, `assumed`, or `needs-clarification` (Notion: tags) to record validation
+  explicitly instead of letting "closed" imply "validated".
+- **CU tier labels** — `cu:basic`, `cu:intermediate`, `cu:advanced` — set the tier
+  directly on any tool that has labels.
+
+## Track movement, not just state
+
+Each sync snapshots per-item scores to `.cu-history.json` and the next sync reports
+what moved: average trend, biggest drops and rises, new items. Commit the file (or
+cache it in CI) to keep the trail. Disable with `--no-history`.
+
+## Use it as a CI gate
+
+```bash
+certainty-units sync --fail-below 50   # exit 1 if avg certainty < 50%
+```
+
+Put it in front of a sprint kickoff or release train to block on too much uncertainty.
+
+## Post to Slack
+
+```bash
+certainty-units sync --slack-webhook https://hooks.slack.com/services/…
+```
+
+Posts the summary and least-certain items to a channel (or set `output.slackWebhook`
+in the config).
+
+## Supported sources
+
+| Tool | Status | Auth |
+|------|--------|------|
+| GitHub Issues | ✅ | none for public repos, token for private |
+| Linear | ✅ | API key |
+| Jira | ✅ | API token |
+| Notion | ✅ | API key |
+| Monday.com | 🚧 coming | |
+| ClickUp | 🚧 coming | |
+
+## Config reference
+
+```yaml
+project: My Project
+source: github          # github | linear | jira | notion
+
+github:
+  repo: owner/name
+  token: ${GITHUB_TOKEN}       # optional for public repos
+  # state: all                 # all | open | closed
+  # limit: 500                 # most recently updated issues to fetch
+
+linear:
+  apiKey: ${LINEAR_API_KEY}    # env var expansion supported
+  teamId: your-team-id
+
+jira:
+  host: yourteam.atlassian.net
+  email: you@example.com
+  apiToken: ${JIRA_API_TOKEN}
+  projectKey: MYPROJECT
+
+notion:
+  apiKey: ${NOTION_API_KEY}
+  databaseId: your-database-id
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md       # optional
+  history: .cu-history.json    # optional — score snapshots for deltas
+  # slackWebhook: https://hooks.slack.com/services/…
+```
+
+### Field mapping
+
+Every tool uses different status names. Override the defaults:
+
+```yaml
+linear:
+  apiKey: ${LINEAR_API_KEY}
+  teamId: abc123
+  fieldMap:
+    validation_status:
+      field: state.type       # dot-path into the Linear issue object
+      map:
+        completed: validated
+        started: assumed
+    cu_tier:
+      field: estimate
+      map:
+        1: basic
+        3: intermediate
+        8: advanced
+```
+
+## Automate with GitHub Actions
+
+1. Copy [examples/cu-report.yml](examples/cu-report.yml) to `.github/workflows/` in your repo
+2. Add your API key as a repo secret (`LINEAR_API_KEY`, or nothing for public GitHub repos)
+3. Enable GitHub Pages → the report publishes every Monday, with week-over-week deltas
+
+## License
+
+MIT — free to use, modify, and embed.
+
+---
+
+Built on the [Certainty Units](https://propozel.com) methodology.

package/examples/cu-report.yml

@@ -0,0 +1,48 @@
+name: Certainty Units Report
+
+on:
+  schedule:
+    - cron: '0 8 * * 1'   # every Monday at 8am UTC
+  workflow_dispatch:        # also runnable manually
+
+permissions:
+  contents: write
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # Keep score history across runs so each report shows what moved
+      - name: Restore sync history
+        uses: actions/cache@v4
+        with:
+          path: .cu-history.json
+          key: cu-history-${{ github.run_id }}
+          restore-keys: cu-history-
+
+      - name: Generate report
+        env:
+          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+          # JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+          # NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
+          # GITHUB_TOKEN:   ${{ secrets.GITHUB_TOKEN }}   # for source: github
+        run: |
+          npx certainty-units@latest sync --json
+          # add --slack-webhook ${{ secrets.SLACK_WEBHOOK }} to post the summary
+          # add --fail-below 50 to fail this job when avg certainty drops too low
+
+      # Publish only the report, never the repo checkout
+      - name: Stage report
+        run: mkdir -p public && cp cu-report.html public/index.html
+
+      - name: Publish to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

package/examples/github.yaml

@@ -0,0 +1,15 @@
+project: My GitHub Project
+source: github
+
+github:
+  repo: owner/name            # e.g. vercel/next.js
+  # token: ${GITHUB_TOKEN}    # uncomment for private repos / higher rate limits
+
+  # GitHub has no priority field — set CU tier with labels on your issues:
+  #   cu:basic  cu:intermediate  cu:advanced
+  # And record validation explicitly with labels:
+  #   validated  assumed  needs-clarification
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md

package/examples/jira.yaml

@@ -0,0 +1,23 @@
+project: My Jira Project
+source: jira
+
+jira:
+  host: yourteam.atlassian.net
+  email: you@example.com
+  apiToken: ${JIRA_API_TOKEN}   # create at id.atlassian.com/manage-profile/security/api-tokens
+  projectKey: MYPROJECT
+
+  # Uncomment to override default field mappings
+  # jql: 'project = MYPROJECT AND sprint in openSprints()'   # custom JQL filter
+  # fieldMap:
+  #   validation_status:
+  #     field: fields.status.name
+  #     map:
+  #       "Done": validated
+  #       "In Review": assumed
+  #       "In Progress": assumed
+  #       "To Do": unvalidated
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md

package/examples/linear.yaml

@@ -0,0 +1,25 @@
+project: My Linear Project
+source: linear
+
+linear:
+  apiKey: ${LINEAR_API_KEY}
+  teamId: your-team-id   # find at linear.app/settings → your team URL
+
+  # Uncomment and adjust to match your team's field conventions
+  # fieldMap:
+  #   cu_tier:
+  #     field: estimate     # use story points as CU tier proxy
+  #     map:
+  #       1: basic
+  #       3: intermediate
+  #       8: advanced
+  #   validation_status:
+  #     field: state.type
+  #     map:
+  #       completed: validated
+  #       started: assumed
+  #       triage: needs_clarification
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md

package/examples/notion.yaml

@@ -0,0 +1,28 @@
+project: My Notion Project
+source: notion
+
+notion:
+  apiKey: ${NOTION_API_KEY}     # create at notion.so/my-integrations
+  databaseId: your-database-id  # from the database URL: notion.so/xxx/<database-id>?v=...
+
+  fieldMap:
+    title_field:    { field: Name }       # column that holds the item title
+    assignee_field: { field: Assignee }
+    estimate_field: { field: Estimate }   # number column for CU value
+    validation_status:
+      field: Status                       # your Status column name
+      map:
+        Done: validated
+        "In Progress": assumed
+        "To Do": unvalidated
+        Backlog: unvalidated
+    cu_tier:
+      field: Priority                     # your Priority column name
+      map:
+        High: advanced
+        Medium: intermediate
+        Low: basic
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "certainty-units",
+  "version": "0.2.0",
+  "description": "Certainty scoring for project work items — connects to Linear, Jira, Notion, GitHub Issues",
+  "type": "module",
+  "bin": {
+    "certainty-units": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["project-management", "certainty", "linear", "jira", "notion", "github", "agile", "hill-chart"],
+  "license": "MIT",
+  "author": "Nhan Nguyen <nhan@naucode.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/2ngnhan/certainty-units.git"
+  },
+  "homepage": "https://github.com/2ngnhan/certainty-units#readme",
+  "bugs": "https://github.com/2ngnhan/certainty-units/issues",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/adapters/github.js

@@ -0,0 +1,96 @@
+// GitHub Issues adapter — maps repo issues to CU items via REST API.
+// Works without a token on public repos (rate-limited); set github.token for
+// private repos or higher limits.
+
+import {
+  applyMap, mergeFieldMap,
+  extractAcceptanceCriteria, validationFromLabels, tierFromLabels,
+} from './util.js'
+
+const GITHUB_API = 'https://api.github.com'
+
+async function githubFetch(url, token) {
+  const headers = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  }
+  if (token) headers.Authorization = `Bearer ${token}`
+  const res = await fetch(url, { headers })
+  if (!res.ok) throw new Error(`GitHub API ${res.status}: ${await res.text()}`)
+  // cursor-based pagination: GitHub puts the next-page URL in the Link header
+  const next = res.headers.get('link')?.match(/<([^>]+)>;\s*rel="next"/)?.[1] ?? null
+  return { data: await res.json(), next }
+}
+
+// Most recently updated first, capped so a huge backlog doesn't hang the sync.
+async function fetchAllIssues(repo, token, { state = 'all', limit = 500 } = {}) {
+  const issues = []
+  let url = `${GITHUB_API}/repos/${repo}/issues?state=${state}&sort=updated&direction=desc&per_page=100`
+  while (url && issues.length < limit) {
+    const { data, next } = await githubFetch(url, token)
+    // the issues endpoint also returns pull requests — skip them
+    issues.push(...data.filter(i => !i.pull_request))
+    url = next
+  }
+  return issues.slice(0, limit)
+}
+
+const DEFAULT_MAP = {
+  validation_status: {
+    field: 'state_reason',
+    map: {
+      completed:   'validated',
+      not_planned: 'unvalidated',
+      reopened:    'assumed',
+    },
+    default: 'unvalidated',
+  },
+}
+
+function workflowStatus(issue) {
+  if (issue.state === 'closed') return 'done'
+  return issue.assignee ? 'in_progress' : 'todo'
+}
+
+export async function fetchItems(config) {
+  const { repo, token, state, limit } = config
+  if (!repo || !repo.includes('/')) {
+    throw new Error('github.repo is required (e.g. owner/name)')
+  }
+
+  const effectiveLimit = limit ?? 500
+  const issues = await fetchAllIssues(repo, token, { state, limit: effectiveLimit })
+  if (issues.length >= effectiveLimit) {
+    console.error(`  note: capped at ${issues.length} most recently updated issues (set github.limit to raise)`)
+  }
+  const fieldMap = mergeFieldMap(DEFAULT_MAP, config.fieldMap)
+
+  return issues.map(issue => {
+    const labels = issue.labels?.map(l => (typeof l === 'string' ? l : l.name)) ?? []
+    const body = issue.body || ''
+
+    return {
+      id:                  String(issue.id),
+      external_id:         `#${issue.number}`,
+      title:               issue.title,
+      description:         body,
+      url:                 issue.html_url,
+      // an explicit validation label beats inferring validation from issue state
+      validation_status:   validationFromLabels(labels) ?? applyMap(issue, fieldMap.validation_status),
+      workflow_status:     workflowStatus(issue),
+      cu_tier:             tierFromLabels(labels),
+      cu_value:            1,
+      evidence:            body,
+      acceptance_criteria: extractAcceptanceCriteria(body),
+      novelty_rating:      null,
+      complexity_rating:   null,
+      dependency_rating:   null,
+      citation_count:      issue.comments ?? 0,
+      assignee:            issue.assignee?.login ?? null,
+      labels,
+      created_at:          issue.created_at,
+      updated_at:          issue.updated_at,
+      source:              'github',
+    }
+  })
+}

package/src/adapters/jira.js

@@ -0,0 +1,122 @@
+// Jira adapter — maps Jira issues to CU items via REST API
+
+import {
+  applyMap, mergeFieldMap,
+  extractAcceptanceCriteria, validationFromLabels, tierFromLabels,
+} from './util.js'
+
+function base64(str) {
+  return Buffer.from(str).toString('base64')
+}
+
+async function jiraFetch(config, path) {
+  const { host, email, apiToken } = config
+  const url = `https://${host}/rest/api/3${path}`
+  const auth = base64(`${email}:${apiToken}`)
+  const res = await fetch(url, {
+    headers: { Authorization: `Basic ${auth}`, Accept: 'application/json' },
+  })
+  if (!res.ok) throw new Error(`Jira API ${res.status}: ${await res.text()}`)
+  return res.json()
+}
+
+async function fetchAllIssues(config) {
+  const { projectKey, jql: customJql } = config
+  const jql = customJql ?? `project = "${projectKey}" ORDER BY updated DESC`
+  const issues = []
+  let startAt = 0
+  const maxResults = 100
+
+  do {
+    const data = await jiraFetch(
+      config,
+      `/search?jql=${encodeURIComponent(jql)}&startAt=${startAt}&maxResults=${maxResults}&fields=summary,description,status,priority,assignee,labels,comment,created,updated,customfield_10016`
+    )
+    issues.push(...data.issues)
+    startAt += data.issues.length
+    if (startAt >= data.total) break
+  } while (true)
+
+  return issues
+}
+
+const DEFAULT_MAP = {
+  validation_status: {
+    field: 'fields.status.statusCategory.key',
+    map: {
+      done:       'validated',
+      'in-progress': 'assumed',
+      new:        'unvalidated',
+    },
+    default: 'unvalidated',
+  },
+  workflow_status: {
+    field: 'fields.status.statusCategory.key',
+    map: {
+      done:          'done',
+      'in-progress': 'in_progress',
+      new:           'todo',
+    },
+    default: 'todo',
+  },
+  cu_tier: {
+    field: 'fields.priority.name',
+    map: {
+      Highest: 'advanced',
+      High:    'advanced',
+      Medium:  'intermediate',
+      Low:     'basic',
+      Lowest:  'basic',
+    },
+    default: null,
+  },
+}
+
+export async function fetchItems(config) {
+  const { host, email, apiToken, projectKey } = config
+  if (!host)       throw new Error('jira.host is required (e.g. yourteam.atlassian.net)')
+  if (!email)      throw new Error('jira.email is required')
+  if (!apiToken)   throw new Error('jira.apiToken is required')
+  if (!projectKey) throw new Error('jira.projectKey is required')
+
+  const issues = await fetchAllIssues(config)
+  const fieldMap = mergeFieldMap(DEFAULT_MAP, config.fieldMap)
+
+  return issues.map(issue => {
+    const f = issue.fields
+    // customfield_10016 is story points in most Jira configs
+    const storyPoints = f.customfield_10016
+
+    // one line per ADF block so heading/checklist detection works downstream
+    const descText = f.description?.content
+      ?.map(b => (b.content ?? []).filter(n => n.type === 'text').map(n => n.text).join(''))
+      ?.filter(Boolean)
+      ?.join('\n') ?? ''
+
+    const labels = f.labels ?? []
+
+    return {
+      id:                  issue.id,
+      external_id:         issue.key,
+      title:               f.summary,
+      description:         descText,
+      url:                 `https://${host}/browse/${issue.key}`,
+      // an explicit validation label beats inferring validation from workflow state
+      validation_status:   validationFromLabels(labels) ?? applyMap(issue, fieldMap.validation_status),
+      workflow_status:     applyMap(issue, fieldMap.workflow_status),
+      cu_tier:             tierFromLabels(labels) ?? applyMap(issue, fieldMap.cu_tier),
+      cu_value:            storyPoints ?? 1,
+      evidence:            descText,
+      acceptance_criteria: extractAcceptanceCriteria(descText),
+      novelty_rating:      null,
+      complexity_rating:   null,
+      dependency_rating:   null,
+      citation_count:      f.comment?.total ?? 0,
+      assignee:            f.assignee?.displayName ?? null,
+      labels,
+      created_at:          f.created,
+      updated_at:          f.updated,
+      source:              'jira',
+    }
+  })
+}