codewhale.history 2.9.3 → 2.10.0

package/README.md

@@ -87,6 +87,7 @@ current project. Two independent dimensions across five difficulty levels:
 **Content theme** (what it's about):
 - **Standard** (default) — Code comprehension or line reconstruction.
 - **SOLID** (`teach me solid`) — Anti-pattern detection and design restoration.
+- **Spec** (`teach me spec`) — Spec-to-code traceability using office docs as source.
 
 | Trigger | Response | Theme | What happens |
 |---------|----------|-------|-------------|
@@ -94,6 +95,8 @@ current project. Two independent dimensions across five difficulty levels:
 | `teach me interactive` | interactive | standard | Lines removed; you restore them |
 | `teach me solid` | passive | solid | Degraded code; you describe fixes |
 | `teach me solid interactive` | interactive | solid | Degraded code; you edit to fix it |
+| `teach me spec` | passive | spec | Spec or code presented; you trace the link |
+| `teach me spec interactive` | interactive | spec | Trace spec to code; you edit code to match |
 
 **Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
 `drill me`
@@ -106,6 +109,7 @@ current project. Two independent dimensions across five difficulty levels:
 | Level | `teach me level 3` or `teach me l3` | Set difficulty 1–5 (default: 3) |
 | Response | `teach me interactive` | Edit the file instead of describing |
 | Theme | `teach me solid` | Anti-pattern detection — fix degraded design |
+| Theme | `teach me spec` | Spec-to-code traceability via office docs |
 | Scope | `teach me services/` | Narrow to a specific file or folder |
 | Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
 
@@ -121,7 +125,7 @@ current project. Two independent dimensions across five difficulty levels:
 
 **Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
 `next` (draw a new snippet) · `level N` · `easier` · `harder` ·
-`interactive` · `passive` · `solid` · `done` (verify work) · `stop`
+`interactive` · `passive` · `solid` · `spec` · `done` (verify work) · `stop`
 
 **At the end** you get a session summary: rounds completed, mode, files covered,
 what you're strong on, what to review, and a suggested next level.

package/_extract_office.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Office Document Text Extractor
+ *
+ * Extracts plain text from .docx, .pptx, and .xlsx files.
+ * Pure Node.js — no external dependencies. Handles ZIP/Open XML internally.
+ *
+ * Usage:
+ *   node _extract_office.js <file.docx|pptx|xlsx>
+ *   codewhale-doc-extract <file.docx|pptx|xlsx>
+ */
+
+const fs = require('fs');
+const zlib = require('zlib');
+
+const filePath = process.argv[2];
+if (!filePath) {
+  console.error('Usage: codewhale-doc-extract <file.docx|pptx|xlsx>');
+  process.exit(1);
+}
+
+const ext = filePath.toLowerCase().split('.').pop();
+const buf = fs.readFileSync(filePath);
+
+// ── ZIP parser ─────────────────────────────────────────────────
+function readZip(buffer) {
+  const entries = [];
+  let offset = 0;
+
+  while (offset < buffer.length - 4) {
+    const sig = buffer.readUInt32LE(offset);
+    if (sig !== 0x04034b50) break;
+
+    const compression = buffer.readUInt16LE(offset + 8);
+    const compressedSize = buffer.readUInt32LE(offset + 18);
+    const nameLen = buffer.readUInt16LE(offset + 26);
+    const extraLen = buffer.readUInt16LE(offset + 28);
+
+    const name = buffer.toString('utf-8', offset + 30, offset + 30 + nameLen);
+    const dataStart = offset + 30 + nameLen + extraLen;
+
+    let data;
+    if (compression === 0) {
+      data = buffer.slice(dataStart, dataStart + compressedSize);
+    } else if (compression === 8) {
+      const raw = buffer.slice(dataStart, dataStart + compressedSize);
+      data = zlib.inflateRawSync(raw);
+    } else {
+      offset = dataStart + compressedSize;
+      continue;
+    }
+
+    entries.push({ name, data: data.toString('utf-8') });
+    offset = dataStart + compressedSize;
+  }
+
+  return entries;
+}
+
+// ── XML text stripper ──────────────────────────────────────────
+function stripXml(xml) {
+  return xml
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#?\w+;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// ── Format-specific extraction ─────────────────────────────────
+const entries = readZip(buf);
+let text = '';
+
+if (ext === 'docx') {
+  const doc = entries.find(e => e.name === 'word/document.xml');
+  if (doc) text = stripXml(doc.data);
+
+  for (const e of entries) {
+    if (e.name.startsWith('word/header') || e.name.startsWith('word/footer')) {
+      text += '\n' + stripXml(e.data);
+    }
+  }
+} else if (ext === 'pptx') {
+  const slides = entries
+    .filter(e => /^ppt\/slides\/slide\d+\.xml$/.test(e.name))
+    .sort((a, b) => {
+      const na = parseInt(a.name.match(/slide(\d+)/)[1]);
+      const nb = parseInt(b.name.match(/slide(\d+)/)[1]);
+      return na - nb;
+    });
+
+  for (let i = 0; i < slides.length; i++) {
+    text += '\n--- Slide ' + (i + 1) + ' ---\n';
+    text += stripXml(slides[i].data) + '\n';
+  }
+
+  for (const e of entries) {
+    if (e.name.startsWith('ppt/notesSlides/notesSlide')) {
+      text += '\n[Notes]\n' + stripXml(e.data) + '\n';
+    }
+  }
+} else if (ext === 'xlsx') {
+  const sst = entries.find(e => e.name === 'xl/sharedStrings.xml');
+  const strings = sst ? extractSharedStrings(sst.data) : [];
+
+  const sheets = entries
+    .filter(e => /^xl\/worksheets\/sheet\d+\.xml$/.test(e.name))
+    .sort((a, b) => {
+      const na = parseInt(a.name.match(/sheet(\d+)/)[1]);
+      const nb = parseInt(b.name.match(/sheet(\d+)/)[1]);
+      return na - nb;
+    });
+
+  for (let i = 0; i < sheets.length; i++) {
+    text += '\n--- Sheet ' + (i + 1) + ' ---\n';
+    text += renderSheet(sheets[i].data, strings) + '\n';
+  }
+} else {
+  console.error('Unsupported format. Use .docx, .pptx, or .xlsx');
+  process.exit(1);
+}
+
+console.log(text.trim());
+
+// ── XLSX helpers ───────────────────────────────────────────────
+function extractSharedStrings(xml) {
+  const matches = xml.match(/<si>([\s\S]*?)<\/si>/g) || [];
+  return matches.map(si => stripXml(si));
+}
+
+function renderSheet(sheetXml, strings) {
+  const rows = sheetXml.match(/<row[\s\S]*?<\/row>/g) || [];
+  let output = '';
+  for (const row of rows) {
+    const cells = row.match(/<c[^>]*>[\s\S]*?<\/c>/g) || [];
+    const rowValues = [];
+    for (const cell of cells) {
+      const tMatch = cell.match(/t="([^"]*)"/);
+      const type = tMatch ? tMatch[1] : null;
+      const vMatch = cell.match(/<v>([^<]*)<\/v>/);
+      if (!vMatch) continue;
+      if (type === 's') {
+        const idx = parseInt(vMatch[1]);
+        rowValues.push(strings[idx] || '');
+      } else {
+        rowValues.push(vMatch[1]);
+      }
+    }
+    if (rowValues.some(v => v.trim())) {
+      output += rowValues.join(' | ') + '\n';
+    }
+  }
+  return output;
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "codewhale.history",
-  "version": "2.9.3",
+  "version": "2.10.0",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",
-    "codewhale-tools-install": "./tools-install.js"
+    "codewhale-tools-install": "./tools-install.js",
+    "codewhale-doc-extract": "./_extract_office.js"
   },
   "files": [
     "_list_sessions.js",
+    "_extract_office.js",
     "tools-install.js",
     "README.md",
     "instructions.md",

package/skills/teach-me/SKILL.md

@@ -12,9 +12,12 @@ current project. Two independent dimensions combine to form each exercise:
 - **`passive`** (default) — You describe your answer in the console.
 - **`interactive`** — You edit the actual file, then say `done` for verification.
 
-**Content theme** (what the exercise is about — trigger keyword `solid`):
+**Content theme** (what the exercise is about — trigger keywords `solid`, `spec`):
 - **Standard** (default) — Code comprehension or line reconstruction.
 - **`solid`** / **`SOLID`** — Anti-pattern detection and design restoration.
+- **`spec`** — Spec-to-code traceability. Exercise shapes alternate randomly:
+  spec → code (show a requirement, ask what code implements it) or code → spec
+  (show code, ask what requirement it satisfies).
 
 | Trigger | Response | Theme | What happens |
 |---------|----------|-------|-------------|
@@ -22,6 +25,8 @@ current project. Two independent dimensions combine to form each exercise:
 | `teach me interactive` | interactive | standard | Lines removed from file; you restore them, say `done` |
 | `teach me solid` | passive | solid | Code rewritten with anti-patterns; you describe design fixes |
 | `teach me solid interactive` | interactive | solid | Code rewritten with anti-patterns; you edit the file to restore good design, say `done` |
+| `teach me spec` | passive | spec | Present spec or code; you describe the link between them |
+| `teach me spec interactive` | interactive | spec | Spec-to-code traceability; you edit code to satisfy a spec, say `done` |
 
 Level, scope, language, and concept modifiers combine freely with any
 combination above.
@@ -48,12 +53,14 @@ Optionally followed by modifiers:
   `teach me error handling`, `teach me type hints`, `teach me threading`
 - `teach me interactive` — edit the file (instead of describing)
 - `teach me solid` / `teach me SOLID` — anti-pattern restoration theme
+- `teach me spec` — spec-to-code traceability theme
 
 Modifiers combine freely: `teach me decorators level 4`,
 `teach me async services/`, `teach me generators l2`,
 `teach me level 2 interactive`, `teach me interactive decorators`,
 `teach me solid level 3`, `teach me SOLID`,
-`teach me solid interactive`
+`teach me solid interactive`,
+`teach me spec`, `teach me spec interactive`
 
 If no level is specified, default to **level 3** and adjust based on
 performance across rounds.
@@ -328,6 +335,94 @@ Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
 ---
 ```
 
+### 2d. Spec Theme — Spec-to-Code Traceability
+
+When content theme is `spec`, the exercise bridges office documents (`.docx`,
+`.pptx`, `.xlsx`) and source code. Each round randomly alternates between two
+exercise shapes.
+
+#### Discovery (Spec Theme)
+
+In addition to the standard code discovery:
+1. Scan the workspace for `.docx`, `.pptx`, and `.xlsx` files.
+2. Extract text from each using `codewhale-doc-extract <file>` (global bin).
+3. Split extracted text into spec fragments: paragraphs, requirement bullets,
+   table rows, slide contents.
+4. Build a combined index: code fragments + spec fragments.
+
+#### Exercise Shapes
+
+Randomly choose one per round (50/50):
+
+**A. Spec → Code** — "Trace forward"
+- Present a spec fragment (a requirement, acceptance criterion, or spec
+  paragraph from an office document).
+- Ask: "What code in this project implements this specification?"
+- The user identifies or describes the matching code.
+
+**B. Code → Spec** — "Trace backward"
+- Present a code snippet from the project.
+- Ask: "What requirement or specification does this code satisfy?"
+- The user identifies the matching spec from the office documents.
+
+The model must verify the link in both directions — does the code actually
+implement the spec, and does the spec actually describe the code?
+
+#### Spec Theme Per-Round Flow
+
+0. **Snapshot git state.** Run `git status --porcelain` on all source files.
+1. **Pick direction** randomly (A or B). Select a fragment from the
+   appropriate index (spec index for A, code index for B).
+2. **Present** the fragment with its source (filename for code, document name
+   + section for specs).
+3. **Instruct** (depends on response mode):
+   - *Passive:* "Trace the link. What [code implements this spec / spec does
+     this code satisfy]? Describe in detail."
+   - *Interactive:* Same prompt, but also: "If the link is broken or missing,
+     edit the code to correctly implement the spec. Say `done` when ready."
+     For interactive: run `//snapshot on` first if the workspace is NOT a git
+     repo.
+4. **Wait.** Do not evaluate until the user signals completion.
+5. **Evaluate** (depends on response mode):
+   - *Passive:* Assess the user's trace — did they correctly identify the
+     link? Is their reasoning sound?
+   - *Interactive:* Re-read the modified files. Compare against the spec.
+     Does the code now correctly implement the requirement?
+6. **Feedback** — structure:
+   ```
+   **Trace accuracy:** [Correct / Partially correct / Incorrect]
+   **What you got right:** [the link they correctly identified]
+   **What you missed:** [missed connections between spec and code]
+   ```
+7. **Restore** (interactive only). If files were modified: `git checkout -- <file>`.
+   If not a git repo, `//snapshot off` to stop backing up.
+
+#### Thinking Suppression (Spec Theme)
+
+Use **Skip** thinking during selection and presentation (steps 1–3). Resume
+normal depth at step 4. Never reveal the correct trace link in reasoning.
+
+#### Spec Theme Presentation Format
+
+```
+---
+## Round N — Level X · passive · spec | Spec → Code
+
+**From:** `QA Cinemas Requirements.pptx` — Slide 4, "Website Requirements (1)"
+
+> The QA Cinemas site needs a home page. The home page shall: Be generally
+> attractive. Be the default for the entire site. Allow site users to navigate
+> to other areas of the site. Have a picture or graphic evocative of the
+> movies or the cinema on it.
+
+**Your turn:** (Passive) What code in this project implements the QA Cinemas
+home page requirement? Trace the link — describe which file(s) and how they
+satisfy these criteria.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
 ### 3. Presentation — Show the Snippet
 
 For each round, present the snippet with its filename:
@@ -565,14 +660,15 @@ nailed everything at-level, say so and highlight the nuance they caught.
 | `harder` | Increase level by 1 (maximum 5). |
 | `interactive` | Switch to interactive (reconstruction) mode for subsequent rounds. |
 | `passive` | Switch to passive (explanation) mode for subsequent rounds. |
-| `solid` / `SOLID` | Switch to SOLID (anti-pattern reconstruction) mode for subsequent rounds. |
-| `done` / `check my work` | (Interactive/SOLID mode) Signal that work is complete. Triggers verification. |
+| `solid` / `SOLID` | Switch to SOLID (anti-pattern reconstruction) theme for subsequent rounds. |
+| `spec` | Switch to spec (spec-to-code traceability) theme for subsequent rounds. |
+| `done` / `check my work` | (Interactive/SOLID/Spec mode) Signal that work is complete. Triggers verification. |
 | `stop` / `end` | End session. Deliver summary. |
 
 ### 5. Loop — Keep Going
 
 After a successful evaluation or a `next` skip, ask:
-"Another round? (yes / no / level N / interactive / passive / solid / stop)"
+"Another round? (yes / no / level N / interactive / passive / solid / spec / stop)"
 
 After a strike-3 reveal, do **not** ask — proceed directly to the next
 round with:
@@ -641,8 +737,11 @@ criteria for the Mechanics axis:
   restore the original lines manually via `edit_file` instead and warn the user.
 - **Restore on session end.** When the session ends, check whether any files
   still contain `# ... N lines removed ...` placeholders or deconstructed
-  code from interactive/SOLID mode. If so, restore them with
+  code from interactive/SOLID/spec mode. If so, restore them with
   `git checkout -- <file>` (or `edit_file` if pre-existing changes).
+- **Spec theme snapshot.** In interactive+spec mode, run `//snapshot on`
+  before file edits if the workspace is not a git repo. Run `//snapshot off`
+  after restoration.
 
 ## Verification
 
@@ -664,3 +763,8 @@ After each round, confirm:
 - (SOLID mode) Individual anti-patterns were NOT annotated or revealed before evaluation
 - (SOLID mode) The file was re-read before evaluating the user's restoration
 - (SOLID mode) Deconstructed files were restored with `git checkout` on round end
+- (Spec theme) Office docs were scanned and extracted during discovery
+- (Spec theme) Exercise direction (spec→code or code→spec) was chosen randomly each round
+- (Spec theme) The trace link was verified in both directions by the model
+- (Spec theme) Interactive mode ran `//snapshot on/off` for non-git workspaces
+- (Spec theme) Modified files were restored after the round