certainty-units 0.2.0 → 0.2.2

package/NOTICE

@@ -0,0 +1,13 @@
+certainty-units
+Copyright (c) 2026 Nhan Nguyen
+
+This software is licensed under the MIT License (see LICENSE).
+
+"Propozel" and "Certainty Units" are trademarks of their respective owner.
+The MIT License covers the source code only; it does not grant any rights
+to use these names, the Propozel logo, or other brand assets. Forks and
+derivative works must use their own product names and branding.
+
+The Certainty Units scoring methodology is documented at
+https://propozel.com and may be freely implemented; this notice restricts
+branding, not ideas.

package/README.md

@@ -177,7 +177,8 @@ linear:
 
 ## License
 
-MIT — free to use, modify, and embed.
+MIT — free to use, modify, and embed. "Propozel" and "Certainty Units" are
+trademarks; the license covers the code, not the branding (see [NOTICE](NOTICE)).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "certainty-units",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Certainty scoring for project work items — connects to Linear, Jira, Notion, GitHub Issues",
   "type": "module",
   "bin": {
@@ -10,12 +10,22 @@
     "src",
     "examples",
     "LICENSE",
+    "NOTICE",
     "README.md"
   ],
   "scripts": {
     "test": "node --test"
   },
-  "keywords": ["project-management", "certainty", "linear", "jira", "notion", "github", "agile", "hill-chart"],
+  "keywords": [
+    "project-management",
+    "certainty",
+    "linear",
+    "jira",
+    "notion",
+    "github",
+    "agile",
+    "hill-chart"
+  ],
   "license": "MIT",
   "author": "Nhan Nguyen <nhan@naucode.com>",
   "repository": {

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { program } from 'commander'
-import { writeFileSync } from 'fs'
+import { writeFileSync, readFileSync } from 'fs'
 import chalk from 'chalk'
 import { loadConfig, CONFIG_TEMPLATE } from './config.js'
 import { computeCertaintyScore, computeScoreBreakdown, biggestGaps } from './certainty.js'
@@ -20,10 +20,14 @@ async function loadAdapter(source) {
   return import(path)
 }
 
+const { version } = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+)
+
 program
   .name('certainty-units')
   .description('Certainty scoring for project work items')
-  .version('0.1.0')
+  .version(version)
 
 program
   .command('init')

package/src/report.js

@@ -83,6 +83,72 @@ function needsAttention(items) {
   </div>`
 }
 
+// Hill chart — the Propozel visualization, as static inline SVG.
+// Certainty maps onto a sine hill: 0–50 uphill (discovery), 50–100 downhill
+// (execution). Items stack in 5-point buckets; hover a dot for its title.
+export function generateHillChartSVG(items, metrics) {
+  const W = 920, H = 320
+  const PAD = { top: 56, right: 36, bottom: 64, left: 36 }
+  const chartW = W - PAD.left - PAD.right
+  const hillH = H - PAD.top - PAD.bottom
+  const MAX_STACK = 8
+
+  const hillX = s => PAD.left + (s / 100) * chartW
+  const hillY = s => H - PAD.bottom - Math.sin((s / 100) * Math.PI) * hillH * 0.8
+
+  // hill outline + fill
+  const pts = []
+  for (let x = 0; x <= 100; x += 2) pts.push(`${hillX(x).toFixed(1)},${hillY(x).toFixed(1)}`)
+  const curve = pts.join(' ')
+  const baseline = H - PAD.bottom
+
+  // bucket items by 5-point score, stack dots upward
+  const buckets = {}
+  for (const item of items) {
+    const bucket = Math.round((item.certainty_score ?? 0) / 5) * 5
+    ;(buckets[bucket] ??= []).push(item)
+  }
+
+  const dots = []
+  for (const [bucket, group] of Object.entries(buckets)) {
+    const score = Number(bucket)
+    const x = hillX(score).toFixed(1)
+    group.slice(0, MAX_STACK).forEach((item, i) => {
+      const y = (hillY(score) - 12 - i * 13).toFixed(1)
+      const s = item.certainty_score ?? 0
+      dots.push(
+        `<circle cx="${x}" cy="${y}" r="5" fill="${levelColor(s)}" stroke="#fff" stroke-width="1.5">` +
+        `<title>${esc(item.external_id)} · ${esc(item.title)} — ${s}% (${certaintyLevel(s)})</title></circle>`
+      )
+    })
+    if (group.length > MAX_STACK) {
+      const y = (hillY(score) - 12 - MAX_STACK * 13).toFixed(1)
+      dots.push(`<text x="${x}" y="${y}" text-anchor="middle" font-size="10" fill="#6f6f6f">+${group.length - MAX_STACK}</text>`)
+    }
+  }
+
+  const peakX = hillX(50).toFixed(1)
+  const legend = [
+    ['high', '#24a148'], ['medium', '#0f62fe'], ['low', '#f1c21b'], ['uncertain', '#da1e28'],
+  ].map(([label, color], i) =>
+    `<circle cx="${PAD.left + 8 + i * 92}" cy="18" r="4" fill="${color}"/>` +
+    `<text x="${PAD.left + 17 + i * 92}" y="21" font-size="10" fill="#525252">${label}</text>`
+  ).join('')
+
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Hill chart" style="width:100%;height:auto;background:#f4f4f4;border:1px solid #e0e0e0">
+  <style>text { font-family: 'IBM Plex Sans', system-ui, sans-serif }</style>
+  ${legend}
+  <polygon points="${PAD.left},${baseline} ${curve} ${PAD.left + chartW},${baseline}" fill="rgba(0,0,0,0.03)"/>
+  <polyline points="${curve}" fill="none" stroke="#c6c6c6" stroke-width="2"/>
+  <line x1="${peakX}" y1="${PAD.top - 8}" x2="${peakX}" y2="${baseline}" stroke="#c6c6c6" stroke-width="1" stroke-dasharray="4 4"/>
+  <text x="${peakX}" y="${PAD.top - 16}" text-anchor="middle" font-size="11" fill="#6f6f6f">&#9650; Peak certainty</text>
+  <text x="${hillX(25).toFixed(1)}" y="${baseline + 22}" text-anchor="middle" font-size="11" fill="#6f6f6f">Discovery — figuring it out</text>
+  <text x="${hillX(75).toFixed(1)}" y="${baseline + 22}" text-anchor="middle" font-size="11" fill="#6f6f6f">Execution — getting it done</text>
+  <text x="${PAD.left}" y="${H - 14}" font-size="10" fill="#525252" font-family="'IBM Plex Mono', monospace">${metrics.uphill} uphill &#183; ${metrics.downhill} downhill &#183; ${metrics.avgCertaintyScore}% avg certainty &#183; ${metrics.velocity} CU delivered</text>
+  ${dots.join('\n  ')}
+</svg>`
+}
+
 export function generateHTML(items, projectName = 'Project') {
   const metrics = computeCUMetrics(items)
   const sorted = [...items].sort((a, b) => (b.certainty_score ?? 0) - (a.certainty_score ?? 0))
@@ -128,6 +194,14 @@ export function generateHTML(items, projectName = 'Project') {
     ${metricBox('Downhill', metrics.downhill, 'execution zone')}
   </div>
 
+  <h2>Hill chart</h2>
+  <p style="font-size:12px;color:#525252;margin:-8px 0 12px">Left of the peak: still figuring it out. Right: executing with confidence. Hover a dot for the item.</p>
+  ${generateHillChartSVG(items, metrics)}
+  <p style="font-size:11px;color:#8d8d8d;margin:8px 0 32px">
+    Static snapshot of the <a href="https://propozel.com" target="_blank" style="color:#8d8d8d">Certainty Units</a> hill chart.
+    In <a href="https://propozel.com" target="_blank" style="color:#0f62fe;text-decoration:none">Propozel</a>, this chart is live &mdash; items move as your team validates assumptions, and stakeholders watch it update.
+  </p>
+
   ${needsAttention(items)}
 
   <h2>Items by certainty score</h2>