diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..d141615 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +* text=auto eol=lf + +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.zip binary diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 2a6cb20..c13a309 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -12,4 +12,8 @@ jobs: - uses: actions/setup-python@v5 with: python-version: '3.12' + - run: pip install -r site/requirements.txt - run: python3 scripts/validate_repository.py + - run: python3 scripts/run_integrated_tests.py + - run: python3 scripts/validate_public_release.py + - run: mkdocs build --strict diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e343b1..92ed4a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,8 @@ No unreleased changes. ### Added -- Thirteen core humanities research skills with a shared contract, gate report, and handoff structure. -- One Level 3 research orchestrator with explicit state transitions, pause, rollback, stop, and researcher-decision behavior. +- 13 core research skills with a shared contract, gate report, and handoff structure. +- One Level 3 router with explicit state transitions, pause, rollback, stop, and researcher-decision behavior. - Research Specification v1.0, including the research object model, research grammar, language guide, conformance levels, and extension protocol. - Quality gates using `PASS`, `CONDITIONAL PASS`, and `FAIL`. - Research session memory, machine-readable JSON Schemas, deterministic conformance cases, and integrated workflow scenarios. diff --git a/INSTALLATION.md b/INSTALLATION.md index a73fe24..0794e57 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,35 +1,61 @@ # Installation -> Paths beginning with `/EXAMPLE/PATH` are illustrative command examples, not machine-specific paths embedded in the release. +> Paths beginning with `/EXAMPLE/PATH` are illustrative. Do not copy them literally without replacing the source path. -Humanities Superpowers is a repository of Agent Skills and supporting project instructions. Installation differs by agent harness. +Humanities Superpowers contains 13 core research skills and 1 Level 3 router. Project-local installation is recommended for a first test because it is isolated, reviewable, and easy to remove. User-level installation makes the skills available across projects but depends on the current conventions of each agent harness. + +## Verification status + +Tested: + +- Claude Code +- OpenAI Codex + +Installation guidance provided, but not yet independently verified: + +- Cursor + +Other Markdown-capable agents may use the skills manually, but compatibility is not guaranteed. ## Claude Code -Claude Code discovers project skills from: +Use this project-local layout: ```text -.claude/skills//SKILL.md +project/ +├── CLAUDE.md +└── .claude/ + └── skills/ + ├── using-humanities-superpowers/ + │ └── SKILL.md + └── ...13 core skill directories... ``` -For a project-local installation: +Install from a local clone: ```bash mkdir -p .claude/skills cp -R /EXAMPLE/PATH/humanities-superpowers/skills/* .claude/skills/ +cp /EXAMPLE/PATH/humanities-superpowers/CLAUDE.md ./CLAUDE.md ``` -For a user-level installation, copy the skills into your Claude skills directory according to the current Claude Code documentation. Keep `CLAUDE.md` in the project root when project-level routing rules are desired. +For a user-level installation, copy the skill directories into the current Claude Code user skills directory. Consult the current Claude Code documentation before doing so; global paths can change. Keep `CLAUDE.md` in a project root when project-level routing rules are desired. -## Codex +## OpenAI Codex -Codex discovers repository skills under: +Use this project-local layout: ```text -.agents/skills//SKILL.md +project/ +├── AGENTS.md +└── .agents/ + └── skills/ + ├── using-humanities-superpowers/ + │ └── SKILL.md + └── ...13 core skill directories... ``` -Install them into a research repository: +Install from a local clone: ```bash mkdir -p .agents/skills @@ -37,33 +63,94 @@ cp -R /EXAMPLE/PATH/humanities-superpowers/skills/* .agents/skills/ cp /EXAMPLE/PATH/humanities-superpowers/AGENTS.md ./AGENTS.md ``` -Codex reads `AGENTS.md` before work and uses it for project-level instructions. +Codex reads `AGENTS.md` for project-level instructions. For a user-level installation, use the current Codex user-skills location rather than guessing a global path. ## Cursor -The repository includes a project rule at: +The repository provides this rule: ```text .cursor/rules/humanities-superpowers.mdc ``` -Copy the rule and skills into the target project. Cursor compatibility may depend on the current agent and rules implementation; verify loading in the version you use. +The rule refers to `skills/using-humanities-superpowers/SKILL.md`, so the guidance-only project layout is: -## Direct repository use +```text +project/ +├── skills/ +│ ├── using-humanities-superpowers/ +│ │ └── SKILL.md +│ └── ...13 core skill directories... +└── .cursor/ + └── rules/ + └── humanities-superpowers.mdc +``` + +Copy the rule and `skills/` directory into the target project, then verify that your Cursor version loads the rule and can open the router. This route has not yet been independently verified in a target Cursor environment. + +## Avoid nested installation + +Copy the *contents* of the repository's `skills/` directory into the harness skill directory. Do not create `skills/skills/` accidentally. After installation, paths should end in `/SKILL.md`, not `skills//skills/SKILL.md`. + +## Verify the installed files + +For Claude Code, run: + +```bash +find .claude/skills -type f -name SKILL.md | sort +find .claude/skills -type f -name SKILL.md | wc -l +``` + +For Codex, replace `.claude/skills` with `.agents/skills`. The expected result is 14 `SKILL.md` files: 13 core research skills and the `using-humanities-superpowers` router. -You may also clone the repository beside a research project and instruct an agent to read the relevant `skills//SKILL.md`. This is portable but provides less automatic discovery. +PowerShell users can count them with: -## Verification after installation +```powershell +(Get-ChildItem .agents/skills -Recurse -Filter SKILL.md).Count +``` + +## First run -Ask the agent: +Use a minimal prompt that requires the router to expose uncertainty: ```text Use Humanities Superpowers to diagnose the current research state. Do not invent missing sources. Return a routing decision and gate result. ``` -A valid installation should make the orchestrator visible and should preserve missing inputs instead of fabricating them. +A valid installation should make `using-humanities-superpowers` visible and preserve missing inputs instead of fabricating them. + +## Safe read-only pilot + +Do not begin with the only copy of a manuscript. Keep the source unchanged and write agent outputs elsewhere: + +```text +pilot/ +├── original/ # unchanged source copy +├── working/ # disposable working copy +└── output/ # gate reports and proposed revisions +``` + +Tell the agent that `original/` is read-only and that every proposed change must go to `working/` or `output/`. + +## Validate the framework clone + +Run the repository checks from the Humanities Superpowers clone: + +```bash +python3 scripts/validate_repository.py +python3 scripts/run_integrated_tests.py +python3 scripts/validate_public_release.py +``` + +On Windows, use `python` instead of `python3` if that is the available launcher. + +The worked example intentionally returns `FAIL` when its source set is unverified. That result must not be changed to make validation appear successful. + +## Direct repository use + +You may keep the framework beside a research project and instruct an agent to read `skills//SKILL.md` directly. This is portable but provides less automatic discovery. ## Version caution -Agent harness installation paths and plugin formats can change. Before publishing a release, compare this guide against the current official Claude Code, Codex, and Cursor documentation. +Agent installation paths and plugin formats can change. Recheck current official harness documentation before publishing installation claims or changing a user-level setup. diff --git a/MANIFEST.json b/MANIFEST.json index 05dc815..b983f87 100644 --- a/MANIFEST.json +++ b/MANIFEST.json @@ -1,7 +1,7 @@ { "name": "humanities-superpowers", "version": "1.0.0", - "file_count": 142, + "file_count": 143, "files": [ { "path": ".claude-plugin/plugin.json", @@ -23,6 +23,11 @@ "sha256": "fee84ae0b5e1a24a444ffe75f3747ae383325b099a31750e4d020660c3da0958", "bytes": 552 }, + { + "path": ".gitattributes", + "sha256": "837cf8eaab09850d66f19639004480d984060b2f5176ea006716d2ba6e15a107", + "bytes": 86 + }, { "path": ".github/FUNDING.yml", "sha256": "75882f8dd96a744d45633b98042af982f666e5a949106ca48f4d1c3710719bf8", @@ -65,8 +70,8 @@ }, { "path": ".github/workflows/validate.yml", - "sha256": "119e0a00149233b01da3cb635b7a795618d7ce2cb0586fdabc54375817d85b28", - "bytes": 283 + "sha256": "2df7a228e9a2fb252b682f6ab3a427f2f3a2ce4a10a416d61c2923c8008616c1", + "bytes": 477 }, { "path": ".gitignore", @@ -83,10 +88,35 @@ "sha256": "d5f25c5a9a7298462ce019924603976d884b07f6ae1d1dc2ae4ca1ab3f4905d5", "bytes": 963 }, + { + "path": "assets/human-ai-collaboration.svg", + "sha256": "00d910d1cc6c653d7727b7b13534b34dc76f7c55141679f8a608b0ac15edd05f", + "bytes": 2489 + }, + { + "path": "assets/quality-gates.svg", + "sha256": "ad1dc05731f43b9312e4d409a865d905b2b6af214c87bf7bcfbccc0bb53979e1", + "bytes": 3246 + }, + { + "path": "assets/research-lifecycle.svg", + "sha256": "5470bb1c8940fbd63a6b56b8e271ba4f2087cf30ff5afe71b2af6e3b1e89f5bd", + "bytes": 2027 + }, + { + "path": "assets/research-pipeline.svg", + "sha256": "2b0523c2c1f0993f0189c8a91615b17655d3e57d22d10edb15485201764ec411", + "bytes": 2443 + }, + { + "path": "assets/skill-map.svg", + "sha256": "717ab9f3ce60ceb839bd8855cd7fc1565c3f1f81b53626d67110be8806c99749", + "bytes": 3919 + }, { "path": "CHANGELOG.md", - "sha256": "37c733897d1a1bbed8c8106f6f19810fe8b6d8390afd5046429092c235544916", - "bytes": 2085 + "sha256": "464ef94397366f785e906ea072d7e92221a64496be4fdcc2ed3cd0fb5d77afa4", + "bytes": 2053 }, { "path": "CITATION.cff", @@ -113,76 +143,6 @@ "sha256": "04eb0705c232b1db1e54530e3be25db7c7385376f3f582fb81d6b199cf7f7af8", "bytes": 2297 }, - { - "path": "INSTALLATION.md", - "sha256": "baca68282a8ccb2ccf48e4c86867bcfc2988e29f137c693d827f3655be81584f", - "bytes": 2160 - }, - { - "path": "LICENSE", - "sha256": "3e2e4db37e48d28d5b4925edf729f05b77fec01f5ed92f0e776a6f41c8e9da4e", - "bytes": 1070 - }, - { - "path": "MANIFESTO.md", - "sha256": "56c72e5d5b291a4ed317ab1c5f698014fff45f3a279f6d34b7a1d5b2864eeb81", - "bytes": 1049 - }, - { - "path": "PUBLISHING_CHECKLIST.md", - "sha256": "8f1fad9fb1318689de110fea92947d08cdfdfdb4a0fb321b8978e1ff44834514", - "bytes": 1010 - }, - { - "path": "README.ko.md", - "sha256": "5ae4adcc3586eae77f94b113dcad1ad7b5e5eec8dda6d1abe95b97e28264d2f9", - "bytes": 5671 - }, - { - "path": "README.md", - "sha256": "c1c125e23232199356f60b2b9b64f56acbda0a031417f0cf013e3ce34635a4b2", - "bytes": 7679 - }, - { - "path": "ROADMAP.md", - "sha256": "d0b3554366dea1e18566343ba70bef5d3c7c5b6bf845631fa34efadd8d17410a", - "bytes": 779 - }, - { - "path": "SECURITY.md", - "sha256": "9fa704d709a5c0dfd9fbc9265c154825738dda20cf5410922cd30d12c8be75f1", - "bytes": 619 - }, - { - "path": "THIRD_PARTY_NOTICES.md", - "sha256": "50c0549c92432e9b4d6edef6ceb1ebf434705e1365e14d5dec09c383654a7767", - "bytes": 756 - }, - { - "path": "assets/human-ai-collaboration.svg", - "sha256": "00d910d1cc6c653d7727b7b13534b34dc76f7c55141679f8a608b0ac15edd05f", - "bytes": 2489 - }, - { - "path": "assets/quality-gates.svg", - "sha256": "ad1dc05731f43b9312e4d409a865d905b2b6af214c87bf7bcfbccc0bb53979e1", - "bytes": 3246 - }, - { - "path": "assets/research-lifecycle.svg", - "sha256": "5470bb1c8940fbd63a6b56b8e271ba4f2087cf30ff5afe71b2af6e3b1e89f5bd", - "bytes": 2027 - }, - { - "path": "assets/research-pipeline.svg", - "sha256": "2b0523c2c1f0993f0189c8a91615b17655d3e57d22d10edb15485201764ec411", - "bytes": 2443 - }, - { - "path": "assets/skill-map.svg", - "sha256": "1d0bef19bba619c567aaa96cc2975cc8d17fc5c247b6c925d5d457b2c33ef3ae", - "bytes": 3904 - }, { "path": "docs/ANTI_PATTERNS.md", "sha256": "78c0458061918847a96407a3f59b0a3402e636126fbb720147b18976711fd183", @@ -198,35 +158,20 @@ "sha256": "9a0ff5284dee42609b6b92221dd0aec622e11b5ba1805f6565e18ba26488ff26", "bytes": 850 }, - { - "path": "docs/PHILOSOPHY.md", - "sha256": "cd138ee4be6973b43540dd97648197eafc136c01bae75f4ed231907793391eba", - "bytes": 1307 - }, - { - "path": "docs/QUALITY_GATES.md", - "sha256": "b0ad43e92df88cf4e25ab059abaf08710b8347c8b7b309743f4663b37a779768", - "bytes": 732 - }, - { - "path": "docs/SKILL_SCHEMA.md", - "sha256": "878352f811f379e9a96575373afd232888dbe404062da13a263eb34fcae4ace8", - "bytes": 1010 - }, { "path": "docs/integration/INTEGRATED_CONFORMANCE.md", - "sha256": "4589db32e75ee45e910083b25ee7e4598207b5fd5ad2d694c64cf37e22bea7d6", - "bytes": 3124 + "sha256": "2d36f9d5073f53e7fb82e03b224bf05d2ff7c1193102302747a29bddcb0a0c8c", + "bytes": 3150 }, { "path": "docs/integration/RELEASE_BLOCKERS.md", - "sha256": "816a583726452678e5b8b6714ac99dc9c2572cd65ebc9021db10ddefd04e78d0", - "bytes": 1151 + "sha256": "9ca33f9cfdeb45c7b83cf2b25c50fb4932cd146276c23b3e656f2bdfff3df371", + "bytes": 1187 }, { "path": "docs/integration/TEST_COVERAGE.md", - "sha256": "b77b5b8e507e9278824713fddfe615efcb870480ee4b69bdade6160ce59231ca", - "bytes": 1995 + "sha256": "d9c4795b45c60f18fdad80e353a1df53141b148975042a208a3f8994158794a4", + "bytes": 2039 }, { "path": "docs/orchestration/RESEARCH_STATE_MACHINE.md", @@ -243,20 +188,40 @@ "sha256": "13400d8768aadb233f3845873b286a3b07269892e273d6a62801b8711eb593f0", "bytes": 1187 }, + { + "path": "docs/PHILOSOPHY.md", + "sha256": "cd138ee4be6973b43540dd97648197eafc136c01bae75f4ed231907793391eba", + "bytes": 1307 + }, + { + "path": "docs/QUALITY_GATES.md", + "sha256": "b0ad43e92df88cf4e25ab059abaf08710b8347c8b7b309743f4663b37a779768", + "bytes": 732 + }, + { + "path": "docs/release/PRE_PUBLICATION_OPTIMIZATION_REPORT.md", + "sha256": "00208256012821723c4545a8bfe61679b5c60f7583e9e2ae03eb452df91db7ac", + "bytes": 10227 + }, { "path": "docs/release/PUBLIC_RELEASE_CHECKLIST.md", - "sha256": "0c4b1ad17f1478946af1655c85c6d9fbf554143a5a0e290b829797671ec755af", - "bytes": 1937 + "sha256": "4948b58f6c2f44705d6a00dff5e1b13d9abdb1133e6abf628df40d5f6a39351d", + "bytes": 2743 }, { "path": "docs/release/RELEASE_NOTES_v1.0.0.md", - "sha256": "1d5c5f7d57adf37e63cb8c656353c047b6448fcb2d71b95d1bac5377c70ba967", - "bytes": 1018 + "sha256": "5ce57d72225aa580f3e58dbe11ba6460840b14621ae516aa925ac421414ab53b", + "bytes": 1034 + }, + { + "path": "docs/SKILL_SCHEMA.md", + "sha256": "878352f811f379e9a96575373afd232888dbe404062da13a263eb34fcae4ace8", + "bytes": 1010 }, { "path": "docs/social-media-kit/LAUNCH_SEQUENCE.md", - "sha256": "b63ebce6d44ec88d63696a379fd6891352753f597a21efd6880e0f7242a1f3b3", - "bytes": 1792 + "sha256": "4ea188b93a214bb41e38220c3565524cac2b7f639e82766ca89fd713dca28852", + "bytes": 1857 }, { "path": "docs/social-media-kit/README.md", @@ -265,13 +230,13 @@ }, { "path": "docs/social-media-kit/SOCIAL_LAUNCH_EN.md", - "sha256": "384121e33ef17f90624d545818d59272e55b24857d1757aea52e10a54194f650", - "bytes": 7496 + "sha256": "74f3907d829cab15fb4ee6b0ea3852f8ff8021cd31525aedfb3e8f6bb6a36a43", + "bytes": 7673 }, { "path": "docs/social-media-kit/SOCIAL_LAUNCH_KO.md", - "sha256": "595dbac309bbb7be08bf90e9046afd12253d3dfd4a458247fe2ffd889fbe3575", - "bytes": 7908 + "sha256": "ecc93ce65325f11bed09574b9e4015541e4ce62deda16701988dec49c4e1d253", + "bytes": 8130 }, { "path": "docs/specification/CONFORMANCE.md", @@ -300,8 +265,8 @@ }, { "path": "docs/specification/README.md", - "sha256": "1575ad5d2aef544e4a95e80a311a6b80ff0b9c3294241cda233e9598c247b256", - "bytes": 2314 + "sha256": "2027927a9fc94f9f6e73de3fa9115c9c01644eb3bc9c014e53098de644543592", + "bytes": 2340 }, { "path": "docs/specification/RESEARCH_GRAMMAR.md", @@ -318,26 +283,21 @@ "sha256": "b1d1983460fc24fbffa60c5edd5ebc7cf8310fdeb6a6e688360901274b8e1cf0", "bytes": 2935 }, - { - "path": "docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md", - "sha256": "97e72e55ed5f644e29c07853ccca4319014e18b3eb0281eef489a132758aa5be", - "bytes": 36719 - }, { "path": "docs/white-paper/citation-audit.md", "sha256": "a6ae5bf40251f92fedad13c5fe31e29ba1fe4b6fae47d88388810f47f4aa998e", "bytes": 4496 }, + { + "path": "docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md", + "sha256": "3788dd782cb94a85ab398525cffd31ab1af5e81c38da075982c58daf9c5c5266", + "bytes": 36769 + }, { "path": "examples/argument-map-example/README.md", "sha256": "d83ae3d5dea1f7681d9ee640f4f7b2b0d7b0d4eee351415946a36a8f89ec5d16", "bytes": 1459 }, - { - "path": "examples/concept-paper-example/README.md", - "sha256": "1ab0d16bae948d8a020c752403d15b2d865a630d83f9fbd0833807c089dfc148", - "bytes": 854 - }, { "path": "examples/concept-paper-example/input/research-brief.md", "sha256": "4b3ce37d2543e06e493a4baf62d9c8d59c433115ef4273baee24e99b7c153cd6", @@ -379,9 +339,9 @@ "bytes": 1134 }, { - "path": "examples/end-to-end-research-session/README.md", - "sha256": "a4208e65fd7c9f4124cca23f5c43d7c9a736f79f461adf6533a30f31157afa40", - "bytes": 926 + "path": "examples/concept-paper-example/README.md", + "sha256": "1ab0d16bae948d8a020c752403d15b2d865a630d83f9fbd0833807c089dfc148", + "bytes": 854 }, { "path": "examples/end-to-end-research-session/gate-history.md", @@ -393,6 +353,11 @@ "sha256": "d1fe762b4988b0c9678ebd7bbbbe2bad0dc269e4a4e392c055ad73073298470c", "bytes": 472 }, + { + "path": "examples/end-to-end-research-session/README.md", + "sha256": "a4208e65fd7c9f4124cca23f5c43d7c9a736f79f461adf6533a30f31157afa40", + "bytes": 926 + }, { "path": "examples/end-to-end-research-session/session-01.json", "sha256": "71fa9e99280bcf1b0579843a47d5c54fb20c26886a4467ba7641c0ab7fc9bc55", @@ -403,6 +368,21 @@ "sha256": "c615809b66c747069fca88bd8b307394d256414fe0e96783a211955575405e4e", "bytes": 1709 }, + { + "path": "INSTALLATION.md", + "sha256": "b5a9327c5c69ecab50f6a4043da700dcc8dbb75cf8f4b8e062c04ae72a26678b", + "bytes": 5142 + }, + { + "path": "LICENSE", + "sha256": "3e2e4db37e48d28d5b4925edf729f05b77fec01f5ed92f0e776a6f41c8e9da4e", + "bytes": 1070 + }, + { + "path": "MANIFESTO.md", + "sha256": "56c72e5d5b291a4ed317ab1c5f698014fff45f3a279f6d34b7a1d5b2864eeb81", + "bytes": 1049 + }, { "path": "mkdocs.yml", "sha256": "604aa49b5bfa4578409b52855fd91b9e87a8cc8893c3c6e11f85c048c52dee62", @@ -413,6 +393,26 @@ "sha256": "2f4aea6ed58d95174a94b59a9b7f5399ab95f16ab21718ed819b1811d264974f", "bytes": 372 }, + { + "path": "PUBLISHING_CHECKLIST.md", + "sha256": "8f1fad9fb1318689de110fea92947d08cdfdfdb4a0fb321b8978e1ff44834514", + "bytes": 1010 + }, + { + "path": "README.ko.md", + "sha256": "1ffe23596e1ba788a542bf520831ae0542dc71a56e4f04284a62161c4c705ab0", + "bytes": 7435 + }, + { + "path": "README.md", + "sha256": "edcdf5cfe00ab801d9fe4ecb9d356fb263f2827ef33b4c5dc358691fefecaea9", + "bytes": 8237 + }, + { + "path": "ROADMAP.md", + "sha256": "aea8f678b5b7bec6266e746d8ab9af0dda2ee63ae0c3d28ce2d3f0b4e96132bb", + "bytes": 762 + }, { "path": "schemas/gate-report.schema.json", "sha256": "25ed42cfa2dc141adb37a339b431b961110d0ab780f54e75e411dca0899839c1", @@ -435,8 +435,8 @@ }, { "path": "scripts/run_integrated_tests.py", - "sha256": "d3f791fe44f99ae8ea49b70d17d97acf902482c0c37d01e237a7fabfc3c01122", - "bytes": 3314 + "sha256": "b31275b0712884ea4892afd7cf29c681b8f4b48bea946645e610724e4edc107e", + "bytes": 3656 }, { "path": "scripts/validate-skills.sh", @@ -445,34 +445,29 @@ }, { "path": "scripts/validate_public_release.py", - "sha256": "66a0aaed62355378f9811daf0c0d3b70722ad12d13e8fdecc5f2044df21d6446", - "bytes": 3425 + "sha256": "b485506f93b9a1c78a4c2ff2b9ced40d488fc0b5577426e11b911203d34b9753", + "bytes": 7909 }, { "path": "scripts/validate_repository.py", - "sha256": "e2e2e5db81499ce8cc3b761432e5949d960f69651fc6db891b40a995f33f9491", - "bytes": 17120 - }, - { - "path": "site/docs/CODE_OF_CONDUCT.md", - "sha256": "f9ebc4e13b98b32559a92dedf177ca3400dc41fe83cdb28b80c6d976da25e94c", - "bytes": 672 + "sha256": "c4bfff02af95bd3e31d9d7cf81d6af5dee90ad3f911a27e83ff269567cadc6f9", + "bytes": 19841 }, { - "path": "site/docs/DIFFERENCES.md", - "sha256": "04eb0705c232b1db1e54530e3be25db7c7385376f3f582fb81d6b199cf7f7af8", - "bytes": 2297 - }, - { - "path": "site/docs/THIRD_PARTY_NOTICES.md", - "sha256": "50c0549c92432e9b4d6edef6ceb1ebf434705e1365e14d5dec09c383654a7767", - "bytes": 756 + "path": "SECURITY.md", + "sha256": "9fa704d709a5c0dfd9fbc9265c154825738dda20cf5410922cd30d12c8be75f1", + "bytes": 619 }, { "path": "site/docs/acknowledgments.md", - "sha256": "66c20093b6d475b48dff22c5d776ae26136f21f89939a2b0eee74bef8cbf736a", + "sha256": "64c4022e58db25b7f1517924fe43248f56ae21c24ec2f9327d25faebd8902f73", "bytes": 1828 }, + { + "path": "site/docs/CODE_OF_CONDUCT.md", + "sha256": "f9ebc4e13b98b32559a92dedf177ca3400dc41fe83cdb28b80c6d976da25e94c", + "bytes": 672 + }, { "path": "site/docs/contributing.md", "sha256": "fb0b47cb06942a7e535c1815b8528a1e0d53f5baa7c557214c176992d1e77122", @@ -490,13 +485,13 @@ }, { "path": "site/docs/index.md", - "sha256": "2133a00361db4ac210067968557124cc1168497b71bcd0178355134f288718c4", - "bytes": 1665 + "sha256": "70ee44ea7d4d49894383b0b0d788a4967ec5b5e4680a4a49fd1bf42cd3098c88", + "bytes": 1883 }, { "path": "site/docs/installation.md", - "sha256": "2c5d0100fde7ce420b0b391a978bab64317270c47d5756d46728127037c188f6", - "bytes": 2018 + "sha256": "707b053e326ce6bb32f580b33809b944a91b2680c56e3bd3fccf5a53216b426a", + "bytes": 3715 }, { "path": "site/docs/methodology.md", @@ -510,39 +505,44 @@ }, { "path": "site/docs/quick-start.md", - "sha256": "af6fda4019ff480d6851c637d57974cc367248058872556819c0dd2552ca5770", - "bytes": 827 + "sha256": "da6991393210a8e5ae6a9e12d52c016dab5fffa919f3975f0b9bce9831f1d7eb", + "bytes": 1063 }, { "path": "site/docs/release/LAUNCH_SEQUENCE.md", - "sha256": "b63ebce6d44ec88d63696a379fd6891352753f597a21efd6880e0f7242a1f3b3", - "bytes": 1792 + "sha256": "4ea188b93a214bb41e38220c3565524cac2b7f639e82766ca89fd713dca28852", + "bytes": 1857 }, { - "path": "site/docs/release/SOCIAL_LAUNCH_EN.md", - "sha256": "384121e33ef17f90624d545818d59272e55b24857d1757aea52e10a54194f650", - "bytes": 7496 + "path": "site/docs/release/social-launch.md", + "sha256": "963d90aea3a35787fa6a632b752953c8e3f36a364f1ba29ff1913bd2e01ba880", + "bytes": 363 }, { - "path": "site/docs/release/SOCIAL_LAUNCH_KO.md", - "sha256": "595dbac309bbb7be08bf90e9046afd12253d3dfd4a458247fe2ffd889fbe3575", - "bytes": 7908 + "path": "site/docs/release/SOCIAL_LAUNCH_EN.md", + "sha256": "74f3907d829cab15fb4ee6b0ea3852f8ff8021cd31525aedfb3e8f6bb6a36a43", + "bytes": 7673 }, { - "path": "site/docs/release/social-launch.md", - "sha256": "963d90aea3a35787fa6a632b752953c8e3f36a364f1ba29ff1913bd2e01ba880", - "bytes": 363 + "path": "site/docs/release/SOCIAL_LAUNCH_KO.md", + "sha256": "ecc93ce65325f11bed09574b9e4015541e4ce62deda16701988dec49c4e1d253", + "bytes": 8130 }, { "path": "site/docs/skills.md", - "sha256": "5ccc3a9b3993ba150532c22d342bc75bf9fd2fc3519edf37006caafef166cdf9", - "bytes": 840 + "sha256": "56333b8c52b9c1bfd90b25c846a42f47c97d94d61bf0d9521b14049a7fd8c32b", + "bytes": 968 }, { "path": "site/docs/state-machine.md", "sha256": "e52083c1ea6d55e1733a3d5496f607338d4e38437532d18c52a7c6de2383b29b", "bytes": 3918 }, + { + "path": "site/docs/THIRD_PARTY_NOTICES.md", + "sha256": "50c0549c92432e9b4d6edef6ceb1ebf434705e1365e14d5dec09c383654a7767", + "bytes": 756 + }, { "path": "site/docs/white-paper.md", "sha256": "cd4980f418b3148c8a603cde8d1ae584914c12f7c13565abf9bfa8ed5197cc05", @@ -698,6 +698,11 @@ "sha256": "869c0e65944c194130036d8f33a59e69a657338b53f8099f4a846aa917b98eeb", "bytes": 1675 }, + { + "path": "THIRD_PARTY_NOTICES.md", + "sha256": "50c0549c92432e9b4d6edef6ceb1ebf434705e1365e14d5dec09c383654a7767", + "bytes": 756 + }, { "path": "workflows/respond-to-reviewers.md", "sha256": "ceec392cd28c06f8757d895f31aade5c70fb81ba8d29591c7282ebeef86ccaee", diff --git a/README.ko.md b/README.ko.md index 6056392..4bdd316 100644 --- a/README.ko.md +++ b/README.ko.md @@ -8,7 +8,7 @@ Humanities Superpowers는 유창한 AI 산출물이 가장 위험해지는 순간을 늦추고 점검합니다. 연구 질문 형성, 개념 정의, 주장과 근거 연결, 반론 검토, 인용 검증, 제출 가능 여부 판단을 명시적인 절차로 바꿉니다. -AI는 정리하고 비교하며 문제를 표시할 수 있습니다. 그러나 해석, 출처 확인, 윤리적 판단, 개념적 선택, 최종 저자 책임은 연구자에게 남습니다. +13개 핵심 연구 스킬과 그중 필요한 최소 경로를 선택하는 1개의 Level 3 라우터를 제공합니다. AI는 정리하고 비교하며 문제를 표시할 수 있지만, 해석, 출처 확인, 윤리적 판단, 개념적 선택, 최종 저자 책임을 대신하거나 원고의 게재 가능 상태를 보장하지 않습니다.

연구 질문에서 제출 게이트까지의 연구 파이프라인

@@ -20,12 +20,26 @@ cd humanities-superpowers python3 scripts/validate_repository.py ``` +Windows에서 `python3` 명령을 찾지 못하면 `python`을 사용하십시오. + `skills/` 폴더를 사용하는 에이전트의 스킬 디렉터리에 복사하거나 [INSTALLATION.md](INSTALLATION.md)를 따르십시오. 예시 명령: > Humanities Superpowers를 사용해 인공자연과 플랫폼 미학에 관한 연구 질문을 만들어라. 확인된 근거, 해석, 추론, 가설, 미확인 사항을 구분하고 출처를 만들지 마라. +전체 작업 흐름을 실행하려면 다음과 같이 요청할 수 있습니다. + +> `workflows/write-a-paper.md`를 따르되, 각 품질 게이트에서 멈추고 다음 단계로 가기 전에 해결되지 않은 위험을 보고하라. + +## 검증 및 호환 상태 + +**실제 설치·검증 완료:** Claude Code, OpenAI Codex. + +**설치 안내는 제공하지만 독립적인 로딩 검증은 미완료:** Cursor. + +그 밖의 Markdown 기반 에이전트에서도 수동으로 사용할 수 있으나 호환성을 보장하지 않습니다. 검증된 프로젝트 구조, 파일 수 확인법, 원본을 읽기 전용으로 보존하는 파일럿 절차는 [INSTALLATION.md](INSTALLATION.md)를 참조하십시오. + ## 핵심 원칙 - **문장보다 연구가 먼저다.** @@ -36,9 +50,9 @@ python3 scripts/validate_repository.py 자세한 이론적 설명은 [방법론 백서](docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md), [프로젝트 철학](docs/PHILOSOPHY.md), [설계 원칙](docs/DESIGN_PRINCIPLES.md)에서 확인할 수 있습니다. -## 13개 연구 스킬 +## 13개 핵심 연구 스킬 + 1개 Level 3 라우터 -

13개 연구 스킬 지도

+

13개 핵심 연구 스킬 지도

1. 연구 질문 형성 2. 논증 범위 설정 @@ -56,12 +70,18 @@ python3 scripts/validate_repository.py 각 스킬은 호출 조건, 필수 입력, 절차, 중단 신호, 허위 생성 방지 규칙, 완료 기준, 출력 형식, 다음 단계로 구성됩니다. +별도의 `using-humanities-superpowers` 라우터가 연구 상태를 진단하고 13개 핵심 연구 스킬 가운데 필요한 경로를 선택합니다. 따라서 저장소에는 13개 핵심 연구 스킬과 1개 라우터, 모두 14개의 `SKILL.md` 파일이 있습니다. + ## 연구 품질 게이트

연구 품질 게이트와 판정

게이트는 `PASS`, `CONDITIONAL PASS`, `FAIL` 중 하나를 반환합니다. 필요한 근거나 판단이 없으면 실패해야 합니다. 실패는 시스템 오류가 아니라 미해결 학술 위험을 숨기지 않는 장치입니다. +## 인간과 AI의 책임 구분 + +AI는 자료를 정리하고 비교하며 논증을 점검하고 위험을 표시할 수 있습니다. 연구의 중요성, 해석, 출처 검증, 윤리, 개념적 선택, AI 사용 공개와 최종 저자 책임은 연구자에게 남습니다. + ## 예제 [Artificial Nature and Platform Mediation](examples/concept-paper-example/README.md) 예제는 연구 브리프부터 최종 검증까지 진행됩니다. 최종 결과는 의도적으로 `FAIL`입니다. 검증된 출처 묶음이 없기 때문에 제출 가능 판정을 거부합니다. @@ -88,6 +108,8 @@ GitHub: [`@icerain-cmd`](https://github.com/icerain-cmd) · [icerain@jj.ac.kr](m MIT License로 공개합니다. +기여 전에 [CONTRIBUTING.md](CONTRIBUTING.md)를 읽어 주십시오. 인용 정보는 [CITATION.cff](CITATION.cff), 라이선스 전문은 [LICENSE](LICENSE)에서 확인할 수 있습니다. + ## 연구 오케스트레이션 diff --git a/README.md b/README.md index 7626abe..31b500c 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Humanities Superpowers helps researchers slow down the moments where fluent AI output is most dangerous: framing a question, defining concepts, connecting claims to evidence, testing objections, checking citations, and deciding whether a manuscript is ready to submit. -It supports scholarly judgment. It does not replace interpretation, source verification, ethics, or authorship. +It provides 13 core research skills and one Level 3 router that selects the smallest valid route through them. It supports scholarly judgment; it does not replace interpretation, source verification, ethics, or authorship, and it does not promise a publication-ready manuscript.

Research pipeline from question to submission gate

@@ -20,6 +20,8 @@ cd humanities-superpowers python3 scripts/validate_repository.py ``` +On Windows, use `python` instead of `python3` if that is the available launcher. + Copy `skills/` into your agent's skill directory, or follow [INSTALLATION.md](INSTALLATION.md). Then ask: @@ -30,6 +32,14 @@ For a complete workflow: > Follow `workflows/write-a-paper.md`. Stop at every quality gate and report unresolved risks before proceeding. +## Verification and compatibility + +**Tested:** Claude Code and OpenAI Codex. + +**Installation guidance provided, but not yet independently verified:** Cursor. + +Other Markdown-capable agents may use the skills manually, but compatibility is not guaranteed. Product conventions can change; see [INSTALLATION.md](INSTALLATION.md) for the tested project layouts, file-count checks, and a read-only pilot workflow. + ## Why it exists AI agents can produce polished academic prose before the underlying research has been verified. Humanities research requires a different discipline: conceptual lineage, close reading, argumentative restraint, traceable evidence, serious counterarguments, and explicit uncertainty. @@ -42,7 +52,7 @@ The framework therefore organizes work around three commitments: Read the [methodology white paper](docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md), [project philosophy](docs/PHILOSOPHY.md), and [design principles](docs/DESIGN_PRINCIPLES.md). -## Thirteen research skills +## 13 core research skills + 1 Level 3 router

Map of thirteen Humanities Superpowers skills

@@ -64,6 +74,8 @@ Read the [methodology white paper](docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE Each skill defines invocation conditions, required inputs, a procedure, stop signals, anti-fabrication rules, completion criteria, output records, and next steps. +The separate `using-humanities-superpowers` router diagnoses research state and selects among these 13 core skills. The repository therefore contains 14 `SKILL.md` files: 13 core research skills and 1 router. + ## Research quality gates

Eight research quality gates and their possible statuses

@@ -101,10 +113,6 @@ Humanities Superpowers does not guarantee truth, originality, acceptance, or cit See [ANTI_PATTERNS.md](docs/ANTI_PATTERNS.md) for common failure modes. -## Supported environments - -The repository provides manifests or copy-based installation routes for OpenAI Codex, Claude Code, Cursor, and agents capable of reading Markdown skills and project instructions. Product conventions change; compatibility does not imply marketplace endorsement. See [INSTALLATION.md](INSTALLATION.md). - ## Origin and independence Humanities Superpowers was inspired by Jesse Vincent's [`obra/superpowers`](https://github.com/obra/superpowers), which applies composable skills and systematic verification to coding agents. This project independently adapts that general design idea to humanities research. diff --git a/ROADMAP.md b/ROADMAP.md index c2b46eb..6e398b1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5,8 +5,8 @@ - Public repository foundation and bilingual documentation - Methodology white paper and quality-gate rationale - Research Specification v1.0 -- Thirteen substantive skills at Conformance Level 2 -- Research orchestrator at Conformance Level 3 +- 13 core research skills at Conformance Level 2 +- 1 router at Conformance Level 3 - Explicit research state machine, rollback protocol, and resumable session record ## Next: Phase 3-F (complete) diff --git a/VALIDATION_REPORT.txt b/VALIDATION_REPORT.txt deleted file mode 100644 index b95b738..0000000 --- a/VALIDATION_REPORT.txt +++ /dev/null @@ -1,24 +0,0 @@ -# Humanities Superpowers v1.0.0 Release Candidate Validation - -Generated: 2026-07-19T06:28:03Z - -## Integrated tests -PASS: 8 integrated scenarios, 33 steps, 14 skills, 5 decisions - -## Repository validation -PASS: repository validation completed with 0 errors and 0 warning(s) - -## Public release validation -PASS: public release versions, placeholders, metadata, and manifest - -## MkDocs strict build -INFO - Cleaning site directory -INFO - Building documentation to directory: /tmp/hsp-site-build -INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: - - CODE_OF_CONDUCT.md - - DIFFERENCES.md - - THIRD_PARTY_NOTICES.md - - release/LAUNCH_SEQUENCE.md - - release/SOCIAL_LAUNCH_EN.md - - release/SOCIAL_LAUNCH_KO.md -INFO - Documentation built in 0.35 seconds diff --git a/assets/skill-map.svg b/assets/skill-map.svg index 5653908..597c3d8 100644 --- a/assets/skill-map.svg +++ b/assets/skill-map.svg @@ -1,5 +1,5 @@ -Humanities Superpowers skill mapThirteen skills grouped into design, evidence, argument, and verification. +Humanities Superpowers skill mapThirteen core research skills grouped into design, evidence, argument, and verification. 13 composable skills, four research responsibilities 1. Research design @@ -19,4 +19,4 @@ Check terminologystable concepts Respond to reviewcomment → revision trace Submission gatePASS / FAIL with reasons - \ No newline at end of file + diff --git a/docs/integration/INTEGRATED_CONFORMANCE.md b/docs/integration/INTEGRATED_CONFORMANCE.md index 5d82f83..c34f8c9 100644 --- a/docs/integration/INTEGRATED_CONFORMANCE.md +++ b/docs/integration/INTEGRATED_CONFORMANCE.md @@ -2,7 +2,7 @@ ## Purpose -Integrated conformance tests whether Humanities Superpowers behaves as one research workflow rather than 13 core skill documents plus one Level 3 research orchestrator. It checks state transitions, handoffs, rollback targets, gate preservation, session continuity, and the alignment of examples, templates, schemas, and public documentation. +Integrated conformance tests whether Humanities Superpowers behaves as one research workflow rather than 13 core research skills plus 1 Level 3 router. It checks state transitions, handoffs, rollback targets, gate preservation, session continuity, and the alignment of examples, templates, schemas, and public documentation. This phase does **not** claim that every AI harness will make identical judgments. The deterministic test suite verifies repository contracts and declared routing behavior. Cross-harness behavioral evaluation remains a separate empirical task. @@ -60,7 +60,7 @@ README claims MUST match implemented artifacts. The repository MUST NOT advertis Phase 3-F passes when: -- all fourteen skills are represented in at least one integrated scenario; +- all 14 `SKILL.md` files (13 core research skills and 1 router) are represented in at least one integrated scenario; - every routing decision appears in the suite; - every substantive skill has at least one incoming or outgoing handoff; - rollback, pause, researcher-decision, and stop paths are exercised; diff --git a/docs/integration/RELEASE_BLOCKERS.md b/docs/integration/RELEASE_BLOCKERS.md index 4ffe530..7dcf234 100644 --- a/docs/integration/RELEASE_BLOCKERS.md +++ b/docs/integration/RELEASE_BLOCKERS.md @@ -8,12 +8,12 @@ No deterministic methodology or integration blocker remains in the conformance s These are hosting and live-environment checks, not claims that the archive has already completed them: -1. Push the repository to GitHub and inspect the rendered README links. -2. Run the GitHub Pages workflow and confirm the deployed site. -3. Test installation in the actual Claude Code, Codex, and Cursor environments used by reviewers. -4. Inspect Git history for sensitive material after the initial commit. -5. Configure repository settings such as Pages, Issues, Discussions, and branch protection. -6. Create and publish the `v1.0.0` GitHub Release. +The public repository, rendered README, Pages site, Issues setting, and published `v1.0.0` Release were independently observed on 2026-07-22. The remaining external actions are: + +1. Test rule and skill loading in an actual Cursor environment; until then, retain the unverified-guidance label. +2. Add repository topics. +3. Decide whether Discussions and branch protection should be enabled. +4. Publish subsequent fixes without moving or rewriting the existing `v1.0.0` tag and Release. ## Explicit non-blocking limitations diff --git a/docs/integration/TEST_COVERAGE.md b/docs/integration/TEST_COVERAGE.md index b64d452..045c65b 100644 --- a/docs/integration/TEST_COVERAGE.md +++ b/docs/integration/TEST_COVERAGE.md @@ -12,7 +12,7 @@ The repository contains three layers of deterministic tests. ## Skill coverage -All fourteen skill documents are exercised by the integrated suite. +All 14 `SKILL.md` files—13 core research skills and 1 Level 3 router—are exercised by the integrated suite. | Skill | Integrated scenarios | |---|---| diff --git a/docs/release/PRE_PUBLICATION_OPTIMIZATION_REPORT.md b/docs/release/PRE_PUBLICATION_OPTIMIZATION_REPORT.md new file mode 100644 index 0000000..ca1d86d --- /dev/null +++ b/docs/release/PRE_PUBLICATION_OPTIMIZATION_REPORT.md @@ -0,0 +1,136 @@ +# Pre-Publication Optimization Report + +## 1. Executive verdict + +**READY WITH MINOR MANUAL ACTIONS** + +No unresolved methodology, integrity, link, secret, or deterministic-validation blocker remains in the local repository. `mkdocs build --strict` passes in an isolated environment created from `site/requirements.txt`. The public Pages site and a successful deployment for the starting `main` commit were independently observed; the pull-request workflow now reruns the full validation set, including MkDocs, before merge. + +## 2. Baseline state + +- Branch: `chore/pre-publication-polish` +- Starting commit: `9dfe112` (`Update release checklist: mark live-repository checks as completed`) +- Existing release tag: `v1.0.0` at `262e1c6`; it was not moved or modified. +- Starting repository status: clean after a fresh clone of the public repository. +- Baseline validation: + - `validate_repository.py` failed under the Windows default console encoding and passed only in forced UTF-8 mode. + - `run_integrated_tests.py` passed 8 scenarios and 33 steps. + - `validate_public_release.py` failed under the Windows default file encoding. In forced UTF-8 mode, it still failed because CRLF checkout conversion invalidated manifest hashes and two tracked paths differed only by case. + - `mkdocs build --strict` was unavailable because MkDocs was not installed. + +## 3. Issues found + +### Blocking + +- The public-release validator was not reproducible on the current Windows checkout. +- `site/docs/DIFFERENCES.md` and `site/docs/differences.md` were identical tracked files that collided on case-insensitive filesystems, leaving the working tree one file short of the manifest. + +### Major + +- README compatibility language did not distinguish tested installations from guidance-only compatibility. +- The Korean README lacked the same compatibility, responsibility, and contribution details as the English README. +- The installation guide did not show complete project-local layouts, guard against `skills/skills/` nesting, verify all 14 `SKILL.md` files, or describe a read-only pilot. +- The public checklist simultaneously described the v1.0.0 GitHub Release as completed and not completed. + +### Moderate + +- References to 13 research skills, 14 skills, and the orchestrator did not consistently distinguish 13 core research skills from 1 Level 3 router. +- Public social copy described Cursor beside tested harnesses without consistently preserving its unverified status. +- A tracked release-candidate validation log was stale after the public v1.0.0 Release. +- The specification index still labeled v1.0.0 a Phase 3-A draft. + +### Minor + +- The repository had no LF policy to protect manifest reproducibility across Git configurations. +- The validator checked link existence but not path-case mismatches on case-insensitive systems. + +## 4. Changes made + +- `README.md`, `README.ko.md`: moved verification status near the Quick Start; stated the project boundary, tested harnesses, Cursor limitation, and the 13-core-plus-router structure; restored semantic parity. +- `INSTALLATION.md`, `site/docs/installation.md`, `site/docs/quick-start.md`: added complete Claude Code and Codex layouts, guidance-only Cursor layout, project-versus-user scope, nesting warnings, file-count checks, a minimal prompt, a read-only pilot layout, and all three validation commands. +- `CHANGELOG.md`, `ROADMAP.md`, `docs/release/RELEASE_NOTES_v1.0.0.md`, `docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md`, `docs/integration/INTEGRATED_CONFORMANCE.md`, `docs/integration/TEST_COVERAGE.md`, `docs/specification/README.md`, `assets/skill-map.svg`, `site/docs/skills.md`: standardized the distinction between 13 core research skills and 1 Level 3 router. +- `docs/social-media-kit/*`, `site/docs/release/*`: distinguished tested Claude Code and OpenAI Codex routes from unverified Cursor guidance and updated the post-release launch sequence. +- `docs/integration/RELEASE_BLOCKERS.md`, `docs/release/PUBLIC_RELEASE_CHECKLIST.md`: reconciled the documents with the public GitHub state observed on 2026-07-22. +- `scripts/validate_repository.py`: made console output Windows-safe, added public-document checks, and added case-sensitive local-link validation. +- `scripts/run_integrated_tests.py`: made the 14-file result explicit as 13 core research skills plus 1 router. +- `scripts/validate_public_release.py`: made all text decoding explicit UTF-8, added count and compatibility checks, normalized text bytes to the repository LF policy, detected path collisions, and added deterministic manifest regeneration. +- `.github/workflows/validate.yml`: expanded the existing `validate` job to run all three validators and `mkdocs build --strict`. +- `.gitattributes`: established LF text normalization while preserving common binary formats. +- `site/docs/DIFFERENCES.md`: removed the case-colliding duplicate; `site/docs/differences.md` remains canonical. +- `VALIDATION_REPORT.txt`: removed the stale release-candidate log. +- `MANIFEST.json`: regenerated after the final release tree was assembled. + +No core skill procedure, router state, schema contract, workflow decision, or intentional example failure was changed. + +## 5. Claims and compatibility audit + +Tested: + +- Claude Code: installation and full pilot reported complete in the supplied release evidence. +- OpenAI Codex: installation and validation complete, including this audit environment. + +Unverified: + +- Cursor: a rule and installation layout are provided, but target-environment loading was not independently verified. +- Other Markdown-capable agents: manual use may be possible; compatibility is not guaranteed. + +Risk-language matches were reviewed in context. Remaining occurrences are negative claims, forbidden examples, submission gates, or narrow procedural contracts. The public descriptions do not claim truth, hallucination prevention, guaranteed citation accuracy, automated peer review, publication readiness, or replacement of scholarly judgment. + +## 6. Documentation consistency + +- README and README.ko now carry equivalent identity, limitation, compatibility, skill/router, quality-gate, attribution, author, license, installation, and intentional-`FAIL` messages. +- Installation guidance uses the actual project-local discovery paths for Claude Code and Codex and the repository's rule-relative layout for Cursor. +- The release checklist no longer duplicates or contradicts the v1.0.0 Release state. +- The repository contains 14 `SKILL.md` files: 13 core research skills and the `using-humanities-superpowers` Level 3 router. +- `obra/superpowers` remains described as inspiration, independently adapted, and not affiliated or endorsed. + +A new Claude Code case study was not added. The external pilot directory may contain unpublished working material, and this audit did not establish a publishable, consent-cleared excerpt. Avoiding accidental disclosure takes priority over adding a launch asset; a sanitized case study can be prepared later. + +## 7. Validation results + +- `python scripts/validate_repository.py`: **PASS**; intentional example `FAIL` preserved. +- `python scripts/run_integrated_tests.py`: **PASS**; 8 scenarios, 33 steps, 14 `SKILL.md` files, 5 decisions. +- `python scripts/validate_public_release.py`: **PASS** after final manifest regeneration. +- `mkdocs build --strict`: **PASS** using the pinned dependencies in `site/requirements.txt`. +- Local link and path-case checks: **PASS** through `validate_repository.py`. +- `git diff --check`: **PASS**. +- `git fsck --no-reflogs --full`: **PASS**. +- Working-tree and reachable-history secret scans: **PASS**; no matching credentials or private-key material. +- Local-path, archive, and large-file scan: **PASS**. + +The current public repository page, documentation URL, and v1.0.0 Release page returned HTTP 200 during the audit. The public Actions history showed a successful documentation deployment for the starting `main` commit, and the changed documentation builds successfully in the local isolated environment. + +## 8. Remaining manual GitHub actions + +- Description: already matches `Structured research skills and quality gates for humanities scholars using AI agents.` +- Topics: the 10 recommended topics are set: `humanities`, `digital-humanities`, `research-methodology`, `ai-agents`, `agent-skills`, `scholarly-writing`, `citation-verification`, `close-reading`, `claude-code`, and `openai-codex`. +- Issues: enabled. +- Discussions: enabled. +- Pages: the homepage points to the public documentation site; the current site and prior deployment are verified. The updated PR check runs a strict documentation build before merge, and the Pages workflow will redeploy after merge to `main`. +- Release: published v1.0.0 verified. Do not rewrite it or move its tag. +- Branch protection: `main` requires the `validate` status check, linear history, and resolved conversations. Force pushes and deletion are disabled. +- Cursor: independently verify rule and skill loading or retain the unverified-guidance label. + +## 9. Release recommendation + +**Prepare v1.0.1.** + +The existing v1.0.0 tag points to an earlier commit, and this audit fixes more than prose: it removes a cross-platform path collision and repairs Windows release validation. Publish these changes as a patch after CI and rendered-document review. Do not force-move `v1.0.0`. + +## 10. Exact public announcement status + +Safe claims: + +- Humanities Superpowers provides 13 core research skills and 1 Level 3 router for AI-assisted humanities research. +- It uses explicit quality gates and preserves unresolved evidence and intentional failure states. +- Claude Code and OpenAI Codex installations have been tested. +- Cursor installation guidance is available but has not yet been independently verified. +- The framework supports scholarly judgment and citation auditing without replacing researcher verification or authorship. + +Claims to avoid: + +- that the framework prevents hallucinations or guarantees truth or citation accuracy; +- that it automatically makes manuscripts publication-ready; +- that it automates or replaces peer review; +- that all agent harnesses behave identically; +- that Cursor loading has been verified before a target-environment test is completed. diff --git a/docs/release/PUBLIC_RELEASE_CHECKLIST.md b/docs/release/PUBLIC_RELEASE_CHECKLIST.md index 96d7c59..a10d7fe 100644 --- a/docs/release/PUBLIC_RELEASE_CHECKLIST.md +++ b/docs/release/PUBLIC_RELEASE_CHECKLIST.md @@ -1,32 +1,42 @@ # Public Release Checklist -This checklist separates checks completed in the release archive from operations that require a live GitHub repository or an installed agent harness. A checked item records evidence available in this archive; it does not claim that external hosting settings have already been configured. +Checked 2026-07-22 against local commit `9dfe112` and the public GitHub repository. A checked item has direct local or public evidence. `[-]` means the item could not be independently verified in this environment; it is not a completion mark. -## Archive checks completed +## Repository checks - [x] Author name, affiliation, email, and GitHub username are populated. - [x] MIT license text is present. -- [x] Acknowledgments, differences, and third-party notices are present. -- [x] No unpublished manuscript, reviewer identity, personal address, API key, access token, or private key was detected by the release validator. -- [x] Text, JSON, YAML, workflow, and metadata placeholders covered by the validator are absent. -- [x] Project, plugin, specification, and conformance versions are aligned to `1.0.0`. -- [x] `MANIFEST.json` was regenerated from the current release tree. -- [x] `python3 scripts/validate_repository.py` passes. -- [x] `python3 scripts/run_integrated_tests.py` passes. -- [x] `python3 scripts/validate_public_release.py` passes. -- [x] `mkdocs build --strict` passes in the release environment. - -## Live-repository checks still required - -- [x] Create or update the GitHub repository and push the release candidate. -- [x] Inspect README and internal links in GitHub's rendered view. -- [x] Confirm that Git history contains no sensitive files. -- [x] Run the GitHub Pages workflow and inspect the deployed site. - -- [x] Create a GitHub Release with the v1.0.0 tag, release notes, and the signed release archive. -- [ ] Test Cursor rule loading in the target environment. -- [ ] Set repository description and topics. -- [ ] Enable Issues and Discussions as intended. -- [ ] Configure Pages to use GitHub Actions. -- [ ] Configure branch protection after the first push. -- [ ] Create and publish Release `v1.0.0` from `docs/release/RELEASE_NOTES_v1.0.0.md`. +- [x] Acknowledgments, differences, and third-party notices preserve the project's inspiration, independent adaptation, and non-affiliation statements. +- [x] Project, plugin, specification, conformance, citation, and skill versions are aligned to `1.0.0`. +- [x] The worked example preserves its intentional final `FAIL`. +- [x] `MANIFEST.json` was regenerated from the final pre-publication tree. +- [x] All three Python validators pass after the pre-publication changes. +- [x] `mkdocs build --strict` passes in an isolated environment using `site/requirements.txt`. +- [x] Final secret, local-path, large-file, and Git object checks pass after the pre-publication changes. + +## Agent-harness verification + +- [x] Claude Code installation and full pilot completed. +- [x] OpenAI Codex installation and validation completed. +- [ ] Cursor rule and skill loading have not been independently verified in a target Cursor environment. +- [-] Other Markdown-capable agents may read the skills manually, but compatibility is not guaranteed. + +## Public GitHub state + +- [x] The repository is public and `main` is the default branch. +- [x] The repository description is `Structured research skills and quality gates for humanities scholars using AI agents.` +- [x] The 10 recommended repository topics are set. +- [x] Issues are enabled. +- [x] Discussions are enabled. +- [x] The repository page and rendered README return HTTP 200. +- [x] The documentation site at `https://icerain-cmd.github.io/humanities-superpowers/` returns HTTP 200, and the public Actions history contains a successful deployment for `main`. +- [x] GitHub Release `v1.0.0` exists and is published, not draft or prerelease. +- [x] `main` branch protection requires the `validate` check, linear history, and conversation resolution; force pushes and branch deletion are disabled. + +## Before the next announcement or patch release + +- [ ] Review and publish the pre-publication changes without moving the existing `v1.0.0` tag. +- [x] Set the recommended repository topics. +- [x] Enable Discussions and protect `main` with the repository validation check. +- [ ] Independently test Cursor loading or continue to label it as unverified guidance. +- [ ] If these changes are released as a patch, prepare `v1.0.1` notes and a new release artifact rather than rewriting the existing `v1.0.0` Release. diff --git a/docs/release/RELEASE_NOTES_v1.0.0.md b/docs/release/RELEASE_NOTES_v1.0.0.md index d92607a..4d6d816 100644 --- a/docs/release/RELEASE_NOTES_v1.0.0.md +++ b/docs/release/RELEASE_NOTES_v1.0.0.md @@ -4,8 +4,8 @@ The first public release introduces a structured research workflow for humanitie ## Included -- 13 Level 2 scholarly research skills; -- a Level 3 research orchestrator; +- 13 core research skills at Level 2; +- 1 Level 3 router (`using-humanities-superpowers`); - research state machine and rollback protocol; - explicit skill contracts and epistemic states; - citation, terminology, peer-review, and submission gates; diff --git a/docs/social-media-kit/LAUNCH_SEQUENCE.md b/docs/social-media-kit/LAUNCH_SEQUENCE.md index 40923e7..26d054f 100644 --- a/docs/social-media-kit/LAUNCH_SEQUENCE.md +++ b/docs/social-media-kit/LAUNCH_SEQUENCE.md @@ -1,14 +1,13 @@ # Recommended Launch Sequence -## Before publication - -1. Create the public GitHub repository. -2. Push the validated repository. -3. Enable GitHub Pages through GitHub Actions. -4. Confirm that the README images and documentation links render correctly. -5. Install the repository once in Claude Code, Codex, and Cursor. -6. Create the `v1.0.0` tag and GitHub Release. -7. Replace `[REPOSITORY_URL]` and `[PAGES_URL]` in the launch copy. +## Before the next public announcement + +1. Run all repository validators and inspect the final diff. +2. Confirm that README images and documentation links render correctly. +3. Retain Claude Code and OpenAI Codex as tested environments. +4. Test Cursor loading, or keep the not-independently-verified label. +5. Replace `[REPOSITORY_URL]` and `[PAGES_URL]` in the launch copy. +6. If releasing fixes, create a new patch release without moving the existing `v1.0.0` tag. ## Launch day diff --git a/docs/social-media-kit/SOCIAL_LAUNCH_EN.md b/docs/social-media-kit/SOCIAL_LAUNCH_EN.md index 641f0e1..89a4a2a 100644 --- a/docs/social-media-kit/SOCIAL_LAUNCH_EN.md +++ b/docs/social-media-kit/SOCIAL_LAUNCH_EN.md @@ -15,11 +15,11 @@ Humanities Superpowers is not a tool that writes papers for researchers. It is a The repository includes: - 13 core research skills, from formulating a question to pre-submission verification -- a research orchestrator that diagnoses the current state and selects the smallest valid workflow +- 1 Level 3 router that diagnoses the current state and selects the smallest valid workflow - quality gates using `PASS`, `CONDITIONAL PASS`, and `FAIL` - concept-lineage mapping, close reading, argument stress testing, citation auditing, terminology control, manuscript review, and peer-review response - rollback to an earlier research stage when a downstream failure reveals an upstream problem -- installation guidance for Claude Code, Codex, and Cursor +- tested installation routes for Claude Code and OpenAI Codex, plus not-yet-verified Cursor guidance - an English white paper, bilingual documentation, worked examples, schemas, and automated validation The project is guided by one sentence: @@ -69,7 +69,7 @@ Rather than automating paper writing, the project supports research judgment acr Unverified citations and unsupported claims are preserved as failures rather than polished into apparently complete scholarship. When a failure originates upstream, the research orchestrator routes the project back to the earliest relevant stage. -The repository supports Claude Code, Codex, and Cursor and is released under the MIT License. +The repository has been tested with Claude Code and OpenAI Codex. It also provides Cursor installation guidance that has not yet been independently verified. The project is released under the MIT License. Repository: [REPOSITORY_URL] Documentation: [PAGES_URL] @@ -91,7 +91,7 @@ AI can generate a polished paragraph long before a research question, source bas - Did the manuscript actually change before the reviewer response says it did? - Is the submission package genuinely ready? -The repository includes 13 research skills, an orchestrator, explicit quality gates, and worked examples. +The repository includes 13 core research skills, 1 Level 3 router, explicit quality gates, and worked examples. [REPOSITORY_URL] @@ -105,11 +105,11 @@ Coding agents increasingly rely on structured planning, tests, debugging, and ve Included: -- 13 Level-2 research skills -- a Level-3 research orchestrator +- 13 core research skills at Level 2 +- 1 Level 3 router - research-object, gate-report, and session schemas - deterministic conformance and integration tests -- Claude Code, Codex, and Cursor installation paths +- tested Claude Code and OpenAI Codex routes, plus unverified Cursor guidance [REPOSITORY_URL] @@ -125,7 +125,7 @@ I therefore wanted to build something different from a better paper-writing prom The result is **Humanities Superpowers**. -It includes 13 research skills and an orchestrator covering the path from research-question formulation to citation auditing, manuscript review, peer-review revision, and submission verification. I hope it can grow as a public methodology that researchers use, criticize, and improve together. +It includes 13 core research skills and 1 Level 3 router covering the path from research-question formulation to citation auditing, manuscript review, peer-review revision, and submission verification. I hope it can grow as a public methodology that researchers use, criticize, and improve together. [REPOSITORY_URL] diff --git a/docs/social-media-kit/SOCIAL_LAUNCH_KO.md b/docs/social-media-kit/SOCIAL_LAUNCH_KO.md index 68ab565..5c811fe 100644 --- a/docs/social-media-kit/SOCIAL_LAUNCH_KO.md +++ b/docs/social-media-kit/SOCIAL_LAUNCH_KO.md @@ -14,12 +14,12 @@ Humanities Superpowers는 AI가 논문을 대신 써주는 도구가 아닙니 프로젝트에는 다음이 포함되어 있습니다. -- 연구 질문 형성부터 제출 전 검증까지 이어지는 13개 핵심 스킬 -- 현재 연구 상태를 진단하고 필요한 스킬을 연결하는 연구 오케스트레이터 +- 연구 질문 형성부터 제출 전 검증까지 이어지는 13개 핵심 연구 스킬 +- 현재 연구 상태를 진단하고 필요한 스킬을 연결하는 1개 Level 3 라우터 - `PASS`, `CONDITIONAL PASS`, `FAIL`로 작동하는 연구 품질 게이트 - 인용 감사, 개념 계보, 정밀 읽기, 논증 스트레스 테스트, 심사의견 대응 - 실패 원인이 발견되면 이전 단계로 돌아가는 rollback 방식 -- Claude Code, Codex, Cursor용 설치 안내 +- Claude Code와 OpenAI Codex의 검증된 설치 경로 및 아직 독립 검증되지 않은 Cursor 안내 - 영문 백서, 한·영문 문서, 실제 예제와 자동 검증 스크립트 이 프로젝트의 핵심 원칙은 단순합니다. @@ -70,7 +70,7 @@ AI가 논문을 대신 쓰게 하는 도구가 아니라, 연구 질문·개념 이 프로젝트는 논문 자동 작성 도구가 아니라 연구 질문 형성, 범위 설정, 개념 계보, 선행연구 대화, 정밀 읽기, 논증 설계, 반론 검토, 인용 감사, 용어 일관성, 심사의견 대응, 제출 전 검증을 연결하는 연구 품질 프레임워크입니다. -검증되지 않은 인용이나 과도한 주장은 `FAIL`로 남기며, 문제가 발견되면 원인이 발생한 이전 단계로 되돌아가도록 설계했습니다. Claude Code, Codex, Cursor에서 사용할 수 있고 MIT License로 공개합니다. +검증되지 않은 인용이나 과도한 주장은 `FAIL`로 남기며, 문제가 발견되면 원인이 발생한 이전 단계로 되돌아가도록 설계했습니다. Claude Code와 OpenAI Codex에서 설치·검증했고, Cursor에는 아직 독립 검증되지 않은 설치 안내를 제공합니다. MIT License로 공개합니다. 저장소: [REPOSITORY_URL] 문서: [PAGES_URL] @@ -92,7 +92,7 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 - 심사의견에 답변서만 쓰고 원고 수정은 빠뜨리지 않았는가? - 지금 원고는 정말 제출 가능한가? -13개 연구 스킬과 제출 전 품질 게이트를 무료로 공개했습니다. +13개 핵심 연구 스킬과 1개 Level 3 라우터, 제출 전 품질 게이트를 무료로 공개했습니다. [REPOSITORY_URL] @@ -104,13 +104,13 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 **Humanities Superpowers**는 composable agent skills의 발상을 인문학 연구 방법론으로 옮긴 오픈소스 프로젝트입니다. -- 13 Level-2 research skills -- Level-3 research orchestrator +- 13 core research skills at Level 2 +- 1 Level 3 router - research state machine - quality gates and rollback - research-object and session JSON schemas - deterministic conformance tests -- Claude Code, Codex, Cursor support +- tested Claude Code and OpenAI Codex routes, plus unverified Cursor guidance [REPOSITORY_URL] @@ -126,7 +126,7 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 그 결과가 Humanities Superpowers입니다. -이 프로젝트는 연구 질문부터 인용 감사, 논증 검토, 심사의견 대응, 제출 전 검증까지 13개 스킬과 연구 오케스트레이터로 구성되어 있습니다. 아직 부족하겠지만, 연구자들이 함께 사용하고 비판하며 발전시키는 공개 방법론이 되기를 바랍니다. +이 프로젝트는 연구 질문부터 인용 감사, 논증 검토, 심사의견 대응, 제출 전 검증까지 13개 핵심 연구 스킬과 1개 Level 3 라우터로 구성되어 있습니다. 아직 부족하겠지만, 연구자들이 함께 사용하고 비판하며 발전시키는 공개 방법론이 되기를 바랍니다. [REPOSITORY_URL] diff --git a/docs/specification/README.md b/docs/specification/README.md index 47fd55c..e6dbe63 100644 --- a/docs/specification/README.md +++ b/docs/specification/README.md @@ -1,6 +1,6 @@ # Humanities Superpowers Research Specification v1.0 -**Status:** Phase 3-A normative draft +**Status:** v1.0 normative specification **Specification version:** 1.0.0 **Project version:** 1.0.0 @@ -45,4 +45,4 @@ It does not define a universal method for all humanities disciplines. A conformi - **Evidence conformant:** uncertainty and source verification states are preserved. - **Release conformant:** automated checks pass and unresolved blockers are disclosed. -All 13 core skills conform to Level 2, and the research orchestrator conforms to Level 3. +All 13 core research skills conform to Level 2, and the `using-humanities-superpowers` router conforms to Level 3. diff --git a/docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md b/docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md index 5a1c0a2..f67cd67 100644 --- a/docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md +++ b/docs/white-paper/HUMANITIES_SUPERPOWERS_WHITE_PAPER.md @@ -12,7 +12,7 @@ Version 1.0.0 · July 2026 Generative AI can produce polished academic prose faster than most research workflows can verify it. This asymmetry creates a distinctive risk for humanities scholarship: fluent output may conceal weak questions, unstable concepts, unexamined assumptions, fabricated or misapplied citations, shallow close reading, and premature claims of completion. Existing AI-writing tools usually optimize generation. Humanities Superpowers instead organizes scholarly work around explicit research skills and quality gates. -The framework treats AI as a **scholarly judgment scaffold**, not as an autonomous author. It decomposes humanities research into thirteen substantive skills: research-question formation, argument scoping, concept-lineage mapping, literature dialogue, argument planning, close reading, argument structuring, stress testing, citation auditing, terminology control, manuscript reviewing, peer-review response, and final submission verification. Each skill defines invocation conditions, required inputs, procedures, stop signals, anti-fabrication rules, completion criteria, and structured outputs. A routing skill coordinates their use. +The framework treats AI as a **scholarly judgment scaffold**, not as an autonomous author. It provides 13 core research skills plus 1 Level 3 router. The core skills cover research-question formation, argument scoping, concept-lineage mapping, literature dialogue, argument planning, close reading, argument structuring, stress testing, citation auditing, terminology control, manuscript reviewing, peer-review response, and final submission verification. Each skill defines invocation conditions, required inputs, procedures, stop signals, anti-fabrication rules, completion criteria, and structured outputs. The router coordinates their use without becoming a fourteenth research method. The framework rests on five principles: research precedes prose; uncertainty must remain visible; claims must be proportionate to evidence; concepts require lineage and boundary control; and completion must be demonstrated rather than asserted. These principles are implemented as quality gates that can return `PASS`, `CONDITIONAL PASS`, or `FAIL`. A failed gate is not a system error. It is a refusal to convert unresolved scholarly risk into confident language. @@ -168,7 +168,7 @@ The statement “the paper is complete” is itself a claim. The framework requi --- -## 5. The thirteen substantive skills +## 5. The 13 core research skills ### 5.1 Formulating a research question diff --git a/scripts/run_integrated_tests.py b/scripts/run_integrated_tests.py index c24fa77..a4df71a 100644 --- a/scripts/run_integrated_tests.py +++ b/scripts/run_integrated_tests.py @@ -5,9 +5,13 @@ ROOT=Path(__file__).resolve().parents[1] ALLOWED_DECISIONS={"PROCEED","PAUSE","ROLLBACK","RESEARCHER_DECISION_REQUIRED","STOP"} EXPECTED_SKILLS={p.parent.name for p in (ROOT/'skills').glob('*/SKILL.md')} +ROUTER='using-humanities-superpowers' def main()->int: errors=[] + core_skills=EXPECTED_SKILLS-{ROUTER} + if len(EXPECTED_SKILLS)!=14 or len(core_skills)!=13 or ROUTER not in EXPECTED_SKILLS: + errors.append('expected 14 SKILL.md files: 13 core research skills and 1 router') data=json.loads((ROOT/'tests/integration/scenarios.json').read_text(encoding='utf-8')) scenarios=data.get('scenarios',[]) seen_skills=set(); seen_decisions=set(); total_steps=0 @@ -48,6 +52,10 @@ def main()->int: for e in errors: print('ERROR:',e) print(f'FAIL: {len(errors)} integrated conformance error(s)') return 1 - print(f'PASS: {len(scenarios)} integrated scenarios, {total_steps} steps, {len(seen_skills)} skills, {len(seen_decisions)} decisions') + print( + f'PASS: {len(scenarios)} integrated scenarios, {total_steps} steps, ' + f'{len(seen_skills)} SKILL.md files (13 core research skills + 1 router), ' + f'{len(seen_decisions)} decisions' + ) return 0 if __name__=='__main__': raise SystemExit(main()) diff --git a/scripts/validate_public_release.py b/scripts/validate_public_release.py index ecf9540..e3842be 100755 --- a/scripts/validate_public_release.py +++ b/scripts/validate_public_release.py @@ -1,54 +1,193 @@ #!/usr/bin/env python3 +from __future__ import annotations + from pathlib import Path -import hashlib, json, re, sys, yaml -root=Path(__file__).resolve().parents[1] -errors=[] -required=[ -'mkdocs.yml','site/requirements.txt','.github/workflows/pages.yml','.github/pull_request_template.md', -'.github/ISSUE_TEMPLATE/bug_report.yml','.github/ISSUE_TEMPLATE/skill_proposal.yml', -'docs/release/RELEASE_NOTES_v1.0.0.md','docs/release/PUBLIC_RELEASE_CHECKLIST.md', -'site/docs/index.md','site/docs/quick-start.md','site/docs/skills.md','MANIFEST.json' +import hashlib +import json +import re +import sys + +import yaml + +ROOT = Path(__file__).resolve().parents[1] +MANIFEST_PATH = ROOT / 'MANIFEST.json' +TEXT_EXTENSIONS = {'.md', '.yml', '.yaml', '.json', '.toml', '.txt', '.py', '.cff', '.mdc', '.sh', '.svg', '.xml', '.html', '.css', '.js'} +REQUIRED = [ + 'mkdocs.yml', 'site/requirements.txt', '.github/workflows/pages.yml', + '.github/pull_request_template.md', '.github/ISSUE_TEMPLATE/bug_report.yml', + '.github/ISSUE_TEMPLATE/skill_proposal.yml', + 'docs/release/RELEASE_NOTES_v1.0.0.md', + 'docs/release/PUBLIC_RELEASE_CHECKLIST.md', 'site/docs/index.md', + 'site/docs/quick-start.md', 'site/docs/skills.md', 'LICENSE', + 'CITATION.cff', 'README.md', 'README.ko.md', 'INSTALLATION.md', + 'MANIFEST.json', ] -for f in required: - if not (root/f).exists(): errors.append(f'missing: {f}') -text_ext={'.md','.yml','.yaml','.json','.toml','.txt','.py','.cff','.mdc'} -for f in root.rglob('*'): - if f.is_file() and f.suffix.lower() in text_ext and f.name!='MANIFEST.json' and 'scripts' not in f.parts: - txt=f.read_text(errors='ignore') - for token in ['GITHUB_USERNAME','AUTHOR_NAME','AFFILIATION','email@example.com','maintainer replaces this placeholder','1.0.0-draft.1','0.9.0-preview']: - if token in txt: errors.append(f'placeholder or stale release token {token!r}: {f.relative_to(root)}') -for f in [root/'.github/ISSUE_TEMPLATE/bug_report.yml',root/'.github/ISSUE_TEMPLATE/skill_proposal.yml',root/'.github/workflows/pages.yml',root/'mkdocs.yml']: - try: yaml.safe_load(f.read_text()) - except Exception as e: errors.append(f'invalid yaml {f.relative_to(root)}: {e}') -for skill_file in sorted((root/'skills').glob('*/SKILL.md')): - match=re.search(r'^version:\s*([^\s]+)', skill_file.read_text(), re.MULTILINE) - if not match: - errors.append(f'missing skill version: {skill_file.relative_to(root)}') - elif match.group(1)!='1.0.0': - errors.append(f'skill version is not 1.0.0: {skill_file.relative_to(root)} ({match.group(1)})') -for f in [root/'project.json',root/'.codex-plugin/plugin.json',root/'.claude-plugin/plugin.json',root/'.cursor-plugin/plugin.json']: +ROUTER = 'using-humanities-superpowers' + + +def release_files() -> list[Path]: + files = [] + for path in sorted(ROOT.rglob('*')): + if not path.is_file() or path == MANIFEST_PATH: + continue + if '.git' in path.parts or 'site-build' in path.parts: + continue + if path.name == 'VALIDATION_REPORT.txt': + continue + files.append(path) + return files + + +def canonical_bytes(path: Path) -> bytes: + """Return release bytes with Git's required LF policy applied to text files.""" + data = path.read_bytes() + if path.suffix.lower() in TEXT_EXTENSIONS or path.name in {'.gitignore', '.gitattributes', 'LICENSE'}: + data = data.replace(b'\r\n', b'\n') + return data + + +def manifest_data() -> dict: + files = [] + for path in release_files(): + data = canonical_bytes(path) + files.append({ + 'path': path.relative_to(ROOT).as_posix(), + 'sha256': hashlib.sha256(data).hexdigest(), + 'bytes': len(data), + }) + return { + 'name': 'humanities-superpowers', + 'version': '1.0.0', + 'file_count': len(files), + 'files': files, + } + + +def update_manifest() -> int: + payload = json.dumps(manifest_data(), ensure_ascii=False, indent=2) + '\n' + MANIFEST_PATH.write_bytes(payload.encode('utf-8')) + print(f'UPDATED: MANIFEST.json ({len(manifest_data()["files"])} files)') + return 0 + + +def main() -> int: + errors: list[str] = [] + + for rel in REQUIRED: + if not (ROOT / rel).exists(): + errors.append(f'missing: {rel}') + + seen: dict[str, str] = {} + for path in release_files(): + rel = path.relative_to(ROOT).as_posix() + folded = rel.casefold() + if folded in seen and seen[folded] != rel: + errors.append(f'case-colliding paths: {seen[folded]} and {rel}') + seen[folded] = rel + + for path in release_files(): + if path.suffix.lower() not in TEXT_EXTENSIONS or 'scripts' in path.parts: + continue + text = path.read_text(encoding='utf-8', errors='strict') + for token in [ + 'GITHUB_USERNAME', 'AUTHOR_NAME', 'AFFILIATION', + 'email@example.com', 'maintainer replaces this placeholder', + '1.0.0-draft.1', '0.9.0-preview', + ]: + if token in text: + errors.append(f'placeholder or stale release token {token!r}: {path.relative_to(ROOT)}') + + for path in [ + ROOT / '.github/ISSUE_TEMPLATE/bug_report.yml', + ROOT / '.github/ISSUE_TEMPLATE/skill_proposal.yml', + ROOT / '.github/workflows/pages.yml', ROOT / 'mkdocs.yml', + ]: + try: + yaml.safe_load(path.read_text(encoding='utf-8')) + except Exception as exc: + errors.append(f'invalid yaml {path.relative_to(ROOT)}: {exc}') + + skill_files = sorted((ROOT / 'skills').glob('*/SKILL.md')) + names = {path.parent.name for path in skill_files} + core_names = names - {ROUTER} + if len(skill_files) != 14 or len(core_names) != 13 or ROUTER not in names: + errors.append( + f'expected 14 SKILL.md files (13 core research skills and 1 router); ' + f'found {len(skill_files)} files, {len(core_names)} core skills, router={ROUTER in names}' + ) + for skill_file in skill_files: + text = skill_file.read_text(encoding='utf-8') + match = re.search(r'^version:\s*([^\s]+)', text, re.MULTILINE) + if not match: + errors.append(f'missing skill version: {skill_file.relative_to(ROOT)}') + elif match.group(1) != '1.0.0': + errors.append(f'skill version is not 1.0.0: {skill_file.relative_to(ROOT)} ({match.group(1)})') + + for path in [ + ROOT / 'project.json', ROOT / '.codex-plugin/plugin.json', + ROOT / '.claude-plugin/plugin.json', ROOT / '.cursor-plugin/plugin.json', + ]: + try: + data = json.loads(path.read_text(encoding='utf-8')) + if data.get('version') != '1.0.0': + errors.append(f'version is not 1.0.0: {path.relative_to(ROOT)}') + except Exception as exc: + errors.append(f'invalid json {path.relative_to(ROOT)}: {exc}') + + citation = (ROOT / 'CITATION.cff').read_text(encoding='utf-8') + for value in ['version: 1.0.0', 'family-names: "Lee"', 'given-names: "Yong Wook"', 'license: MIT']: + if value not in citation: + errors.append(f'CITATION.cff missing expected metadata: {value}') + + readme = (ROOT / 'README.md').read_text(encoding='utf-8') + readme_ko = (ROOT / 'README.ko.md').read_text(encoding='utf-8') + installation = (ROOT / 'INSTALLATION.md').read_text(encoding='utf-8') + public_phrases = [ + (readme, '13 core research skills + 1 Level 3 router', 'README.md'), + (readme, '**Tested:** Claude Code and OpenAI Codex.', 'README.md'), + (readme, 'not yet independently verified:** Cursor.', 'README.md'), + (readme_ko, '13개 핵심 연구 스킬 + 1개 Level 3 라우터', 'README.ko.md'), + (readme_ko, '독립적인 로딩 검증은 미완료:** Cursor.', 'README.ko.md'), + (installation, 'Do not create `skills/skills/`', 'INSTALLATION.md'), + ] + for text, phrase, rel in public_phrases: + if phrase not in text: + errors.append(f'{rel} missing required public-release wording: {phrase}') + try: - data=json.loads(f.read_text()) - if data.get('version')!='1.0.0': errors.append(f'version is not 1.0.0: {f.relative_to(root)}') - except Exception as e: errors.append(f'invalid json {f.relative_to(root)}: {e}') -manifest_path=root/'MANIFEST.json' -if manifest_path.exists(): - try: - manifest=json.loads(manifest_path.read_text()) - listed={x['path']:x for x in manifest['files']} - actual=[] - for f in sorted(root.rglob('*')): - if f.is_file() and f!=manifest_path and f.name!='VALIDATION_REPORT.txt' and '.git' not in f.parts and 'site-build' not in f.parts: - rel=f.relative_to(root).as_posix(); actual.append(rel) - h=hashlib.sha256(f.read_bytes()).hexdigest() - item=listed.get(rel) - if not item: errors.append(f'manifest missing file: {rel}') - elif item.get('sha256')!=h or item.get('bytes')!=f.stat().st_size: errors.append(f'manifest mismatch: {rel}') - extra=sorted(set(listed)-set(actual)) - for rel in extra: errors.append(f'manifest lists absent file: {rel}') - if manifest.get('file_count')!=len(actual): errors.append(f'manifest file_count {manifest.get("file_count")} != {len(actual)}') - except Exception as e: errors.append(f'invalid MANIFEST.json: {e}') -if errors: - print('FAIL: public release validation') - print('\n'.join('- '+e for e in errors)); sys.exit(1) -print('PASS: public release versions, placeholders, metadata, and manifest') + listed_manifest = json.loads(MANIFEST_PATH.read_text(encoding='utf-8')) + expected_manifest = manifest_data() + listed = {item['path']: item for item in listed_manifest['files']} + expected = {item['path']: item for item in expected_manifest['files']} + for rel, item in expected.items(): + if rel not in listed: + errors.append(f'manifest missing file: {rel}') + elif listed[rel].get('sha256') != item['sha256'] or listed[rel].get('bytes') != item['bytes']: + errors.append(f'manifest mismatch: {rel}') + for rel in sorted(set(listed) - set(expected)): + errors.append(f'manifest lists absent file: {rel}') + if listed_manifest.get('file_count') != expected_manifest['file_count']: + errors.append( + f'manifest file_count {listed_manifest.get("file_count")} ' + f'!= {expected_manifest["file_count"]}' + ) + if listed_manifest.get('version') != '1.0.0': + errors.append('MANIFEST.json version is not 1.0.0') + except Exception as exc: + errors.append(f'invalid MANIFEST.json: {exc}') + + if errors: + print('FAIL: public release validation') + print('\n'.join('- ' + error for error in errors)) + return 1 + print('PASS: public release versions, counts, compatibility wording, metadata, and manifest') + return 0 + + +if __name__ == '__main__': + if sys.argv[1:] == ['--update-manifest']: + raise SystemExit(update_manifest()) + if sys.argv[1:]: + print('Usage: python3 scripts/validate_public_release.py [--update-manifest]') + raise SystemExit(2) + raise SystemExit(main()) diff --git a/scripts/validate_repository.py b/scripts/validate_repository.py index b13147d..242f00b 100644 --- a/scripts/validate_repository.py +++ b/scripts/validate_repository.py @@ -1,6 +1,7 @@ from __future__ import annotations from pathlib import Path -import json, re, sys +import json, os, re, sys +from urllib.parse import unquote ROOT = Path(__file__).resolve().parents[1] ERRORS: list[str] = [] @@ -20,7 +21,7 @@ "checking-terminology-consistency", "reviewing-manuscript", "responding-to-peer-review", "verifying-before-submission" } -# Router is part of the 13-method set's orchestration layer; substantive set excludes router. +# The router is separate from the 13 core research skills. EXPECTED_SUBSTANTIVE_COUNT = 13 LEVEL2_FOUNDATION_SKILLS = { "formulating-research-question", "scoping-argument-boundary", @@ -100,13 +101,68 @@ def validate_json() -> None: def validate_links() -> None: pattern = re.compile(r"\[[^\]]+\]\((?!https?://|mailto:|#)([^)]+)\)") + actual: dict[str, list[str]] = {} + for candidate in ROOT.rglob('*'): + if '.git' not in candidate.parts: + rel = candidate.relative_to(ROOT).as_posix() + actual.setdefault(rel.casefold(), []).append(rel) for path in ROOT.rglob('*.md'): text=path.read_text(encoding='utf-8') for raw in pattern.findall(text): - target=raw.split('#',1)[0] + target=unquote(raw.split('#',1)[0]).strip('<>') if not target: continue - resolved=(path.parent/target).resolve() - if not resolved.exists(): error(f"{path.relative_to(ROOT)}: broken link -> {raw}") + resolved=Path(os.path.normpath(path.parent / target)) + try: + rel=resolved.relative_to(ROOT).as_posix() + except ValueError: + error(f"{path.relative_to(ROOT)}: link escapes repository -> {raw}") + continue + matches=actual.get(rel.casefold(), []) + if not matches: + error(f"{path.relative_to(ROOT)}: broken link -> {raw}") + elif rel not in matches: + error(f"{path.relative_to(ROOT)}: link case mismatch -> {raw}; actual={matches[0]}") + +def validate_public_documentation() -> None: + required_phrases = { + 'README.md': [ + '13 core research skills + 1 Level 3 router', + '**Tested:** Claude Code and OpenAI Codex.', + '**Installation guidance provided, but not yet independently verified:** Cursor.', + '[INSTALLATION.md](INSTALLATION.md)', + 'Lee Yong Wook', + '[MIT License](LICENSE)', + ], + 'README.ko.md': [ + '13개 핵심 연구 스킬 + 1개 Level 3 라우터', + '**실제 설치·검증 완료:** Claude Code, OpenAI Codex.', + '**설치 안내는 제공하지만 독립적인 로딩 검증은 미완료:** Cursor.', + '[INSTALLATION.md](INSTALLATION.md)', + '이용욱(Lee Yong Wook)', + '[LICENSE](LICENSE)', + ], + 'INSTALLATION.md': [ + 'Tested:', + 'Installation guidance provided, but not yet independently verified:', + '14 `SKILL.md` files: 13 core research skills and the `using-humanities-superpowers` router.', + 'Do not create `skills/skills/`', + 'python3 scripts/validate_public_release.py', + ], + } + for rel, phrases in required_phrases.items(): + text = (ROOT / rel).read_text(encoding='utf-8') + for phrase in phrases: + if phrase not in text: + error(f'{rel}: missing public-release wording: {phrase}') + if not (ROOT / 'LICENSE').exists(): + error('LICENSE is missing') + citation = (ROOT / 'CITATION.cff').read_text(encoding='utf-8') + for phrase in ['version: 1.0.0', 'family-names: "Lee"', 'given-names: "Yong Wook"', 'license: MIT']: + if phrase not in citation: + error(f'CITATION.cff: missing metadata: {phrase}') + release_notes = (ROOT / 'docs/release/RELEASE_NOTES_v1.0.0.md').read_text(encoding='utf-8') + if '# Humanities Superpowers v1.0.0' not in release_notes: + error('release notes do not identify v1.0.0') def validate_example() -> None: base=ROOT/'examples/concept-paper-example' @@ -117,7 +173,7 @@ def validate_example() -> None: if '`FAIL`' not in final: error('worked example must preserve its failing final gate') else: - print('INTENTIONAL FAIL — OK: worked example correctly preserves an unresolved final gate') + print('INTENTIONAL FAIL - OK: worked example correctly preserves an unresolved final gate') focused = [ROOT/'examples/argument-map-example/README.md', ROOT/'examples/terminology-audit-example/README.md'] for path in focused: if not path.exists(): error(f'focused example missing {path.relative_to(ROOT)}') @@ -271,7 +327,7 @@ def validate_placeholders() -> None: error(f"{path.relative_to(ROOT)}: unexpected publication placeholder(s): {sorted(set(matches))}") def main() -> int: - validate_skills(); validate_json(); validate_links(); validate_example(); validate_methodology(); validate_specification(); validate_integration(); validate_placeholders() + validate_skills(); validate_json(); validate_links(); validate_public_documentation(); validate_example(); validate_methodology(); validate_specification(); validate_integration(); validate_placeholders() for msg in WARNINGS: print(f"WARNING: {msg}") for msg in ERRORS: print(f"ERROR: {msg}") if ERRORS: diff --git a/site/docs/DIFFERENCES.md b/site/docs/DIFFERENCES.md deleted file mode 100644 index 0e8f771..0000000 --- a/site/docs/DIFFERENCES.md +++ /dev/null @@ -1,44 +0,0 @@ -# How Humanities Superpowers differs from Superpowers - -Humanities Superpowers is inspired by the idea of composable agent skills, but it is not a direct translation of software-development practices into academic prose. - -| `obra/superpowers` orientation | Humanities Superpowers orientation | -|---|---| -| software development methodology | humanities research methodology scaffold | -| test-driven development | claim–evidence–counterargument verification | -| debugging program behavior | diagnosing conceptual slippage, interpretive overreach, and category errors | -| implementation plans | argument maps and research boundaries | -| code review | manuscript review and reviewer simulation | -| tests before completion | source, terminology, argument, privacy, and submission gates | -| executable correctness | accountable but contestable interpretation | - -## What is retained at the level of principle - -- systematic rather than ad hoc process; -- evidence before completion claims; -- reusable, composable skills; -- explicit conditions for invoking a skill; -- stop conditions when required evidence is missing; -- verification as a distinct final act. - -## What is deliberately changed - -### 1. No humanities equivalent of a passing unit test - -Interpretations cannot usually be reduced to binary tests. The framework therefore checks traceability, proportionality, counterevidence, conceptual consistency, and disclosed uncertainty rather than declaring an interpretation objectively proven. - -### 2. Close reading is not data extraction - -The agent must connect an interpretation to specific formal, rhetorical, textual, visual, or material features. It must also record plausible rival readings. - -### 3. Citations are not decorations - -A citation must exist, be correctly identified, and actually support the claim attached to it. Bibliographic completion is not allowed through guessing. - -### 4. The framework resists ghostwriting - -`structuring-humanities-argument` organizes researcher-provided claims, notes, and evidence. It marks missing warrants and unsupported transitions. It does not authorize the agent to impersonate the researcher's original scholarly judgment. - -### 5. Uncertainty is an output - -When verification fails, the correct result is an unresolved-item list—not fluent filler. diff --git a/site/docs/acknowledgments.md b/site/docs/acknowledgments.md index f3428de..9de4432 100644 --- a/site/docs/acknowledgments.md +++ b/site/docs/acknowledgments.md @@ -16,4 +16,4 @@ We are grateful for the project's clear insistence on systematic process, eviden The debt is architectural rather than disciplinary: composable skills, explicit triggers, stop conditions, and verification before completion. The difference is substantive: software correctness can often be tested against executable behavior, while humanities scholarship requires accountable interpretation, source criticism, conceptual boundaries, and judgments that remain open to contestation. -See [DIFFERENCES.md](DIFFERENCES.md) for a detailed comparison. +See [differences.md](differences.md) for a detailed comparison. diff --git a/site/docs/index.md b/site/docs/index.md index 5594121..d55b7f8 100644 --- a/site/docs/index.md +++ b/site/docs/index.md @@ -6,6 +6,8 @@ Humanities Superpowers is a set of structured research skills, research contract It is designed to reduce the risk that fluent AI output is mistaken for verified scholarship. It does not replace the researcher. It makes research decisions, missing evidence, unresolved objections, citation status, and submission blockers more visible. +The repository contains 13 core research skills and 1 Level 3 router. Claude Code and OpenAI Codex have been tested; Cursor installation guidance is provided but has not yet been independently verified. + ## What it changes Most AI writing workflows move forward continuously: @@ -25,7 +27,7 @@ A failed gate is not hidden. The workflow pauses, requests a researcher decision ## Core promise -The framework does **not** promise truth, originality, publication, or error-free citations. It promises a narrower and observable discipline: +The framework does **not** promise truth, originality, publication, or error-free citations. It instead makes a narrower and observable discipline explicit: - unknown information remains marked as unknown; - claims are not silently widened beyond available evidence; diff --git a/site/docs/installation.md b/site/docs/installation.md index d7f35e3..5173fac 100644 --- a/site/docs/installation.md +++ b/site/docs/installation.md @@ -1,67 +1,115 @@ # Installation -Humanities Superpowers is a repository of Agent Skills and supporting project instructions. Installation differs by agent harness. +Humanities Superpowers contains 13 core research skills and 1 Level 3 router. Project-local installation is recommended for a first test because it is isolated, reviewable, and easy to remove. User-level installation makes the skills available across projects but depends on the current conventions of each agent harness. -## Claude Code +## Verification status + +Tested: + +- Claude Code +- OpenAI Codex + +Installation guidance provided, but not yet independently verified: -Claude Code discovers project skills from: +- Cursor + +Other Markdown-capable agents may use the skills manually, but compatibility is not guaranteed. + +## Claude Code ```text -.claude/skills//SKILL.md +project/ +├── CLAUDE.md +└── .claude/ + └── skills/ + ├── using-humanities-superpowers/ + │ └── SKILL.md + └── ...13 core skill directories... ``` -For a project-local installation: - ```bash mkdir -p .claude/skills -cp -R /path/to/humanities-superpowers/skills/* .claude/skills/ +cp -R /EXAMPLE/PATH/humanities-superpowers/skills/* .claude/skills/ +cp /EXAMPLE/PATH/humanities-superpowers/CLAUDE.md ./CLAUDE.md ``` -For a user-level installation, copy the skills into your Claude skills directory according to the current Claude Code documentation. Keep `CLAUDE.md` in the project root when project-level routing rules are desired. +For a user-level installation, consult the current Claude Code documentation before copying the skills into its user directory. -## Codex - -Codex discovers repository skills under: +## OpenAI Codex ```text -.agents/skills//SKILL.md +project/ +├── AGENTS.md +└── .agents/ + └── skills/ + ├── using-humanities-superpowers/ + │ └── SKILL.md + └── ...13 core skill directories... ``` -Install them into a research repository: - ```bash mkdir -p .agents/skills -cp -R /path/to/humanities-superpowers/skills/* .agents/skills/ -cp /path/to/humanities-superpowers/AGENTS.md ./AGENTS.md +cp -R /EXAMPLE/PATH/humanities-superpowers/skills/* .agents/skills/ +cp /EXAMPLE/PATH/humanities-superpowers/AGENTS.md ./AGENTS.md ``` -Codex reads `AGENTS.md` before work and uses it for project-level instructions. +Codex reads `AGENTS.md` for project-level instructions. Use the current Codex documentation before changing a user-level setup. ## Cursor -The repository includes a project rule at: +The repository provides `.cursor/rules/humanities-superpowers.mdc`. That rule refers to `skills/using-humanities-superpowers/SKILL.md`, so copy both the rule and the repository's `skills/` directory into the project. Then verify that your Cursor version loads the rule and can open the router. This route has not yet been independently verified in a target Cursor environment. -```text -.cursor/rules/humanities-superpowers.mdc -``` +## Avoid nested installation -Copy the rule and skills into the target project. Cursor compatibility may depend on the current agent and rules implementation; verify loading in the version you use. +Copy the *contents* of the repository's `skills/` directory into the harness skill directory. Do not create `skills/skills/`. Paths should end in `/SKILL.md`. -## Direct repository use +## Verify the installed files + +```bash +find .claude/skills -type f -name SKILL.md | sort +find .claude/skills -type f -name SKILL.md | wc -l +``` + +For Codex, replace `.claude/skills` with `.agents/skills`. Expect 14 `SKILL.md` files: 13 core research skills and the `using-humanities-superpowers` router. -You may also clone the repository beside a research project and instruct an agent to read the relevant `skills//SKILL.md`. This is portable but provides less automatic discovery. +PowerShell users can run: -## Verification after installation +```powershell +(Get-ChildItem .agents/skills -Recurse -Filter SKILL.md).Count +``` -Ask the agent: +## First run ```text Use Humanities Superpowers to diagnose the current research state. Do not invent missing sources. Return a routing decision and gate result. ``` -A valid installation should make the orchestrator visible and should preserve missing inputs instead of fabricating them. +## Safe read-only pilot + +Keep the only copy of a manuscript outside the agent's write area: + +```text +pilot/ +├── original/ # unchanged source copy +├── working/ # disposable working copy +└── output/ # gate reports and proposed revisions +``` + +Tell the agent that `original/` is read-only. -## Version caution +## Validate the framework clone + +```bash +python3 scripts/validate_repository.py +python3 scripts/run_integrated_tests.py +python3 scripts/validate_public_release.py +``` + +On Windows, use `python` instead of `python3` if that is the available launcher. + +The worked example intentionally returns `FAIL` when its source set is unverified. Do not change that result to make validation appear successful. + +## Direct repository use -Agent harness installation paths and plugin formats can change. Before publishing a release, compare this guide against the current official Claude Code, Codex, and Cursor documentation. +You may keep the framework beside a research project and instruct an agent to read `skills//SKILL.md` directly. This is portable but provides less automatic discovery. diff --git a/site/docs/quick-start.md b/site/docs/quick-start.md index f2dc10f..38b2e58 100644 --- a/site/docs/quick-start.md +++ b/site/docs/quick-start.md @@ -9,6 +9,8 @@ cd humanities-superpowers ## Ask your agent +Install the framework using the tested project layout in the [Installation Guide](installation.md), then ask: + ```text Use Humanities Superpowers to turn my broad topic about platform interfaces and cultural memory into a precise research question. Do not invent sources. @@ -33,4 +35,7 @@ A valid result includes: ```bash python3 scripts/validate_repository.py python3 scripts/run_integrated_tests.py +python3 scripts/validate_public_release.py ``` + +On Windows, use `python` instead of `python3` if that is the available launcher. diff --git a/site/docs/release/LAUNCH_SEQUENCE.md b/site/docs/release/LAUNCH_SEQUENCE.md index 40923e7..26d054f 100644 --- a/site/docs/release/LAUNCH_SEQUENCE.md +++ b/site/docs/release/LAUNCH_SEQUENCE.md @@ -1,14 +1,13 @@ # Recommended Launch Sequence -## Before publication - -1. Create the public GitHub repository. -2. Push the validated repository. -3. Enable GitHub Pages through GitHub Actions. -4. Confirm that the README images and documentation links render correctly. -5. Install the repository once in Claude Code, Codex, and Cursor. -6. Create the `v1.0.0` tag and GitHub Release. -7. Replace `[REPOSITORY_URL]` and `[PAGES_URL]` in the launch copy. +## Before the next public announcement + +1. Run all repository validators and inspect the final diff. +2. Confirm that README images and documentation links render correctly. +3. Retain Claude Code and OpenAI Codex as tested environments. +4. Test Cursor loading, or keep the not-independently-verified label. +5. Replace `[REPOSITORY_URL]` and `[PAGES_URL]` in the launch copy. +6. If releasing fixes, create a new patch release without moving the existing `v1.0.0` tag. ## Launch day diff --git a/site/docs/release/SOCIAL_LAUNCH_EN.md b/site/docs/release/SOCIAL_LAUNCH_EN.md index 641f0e1..89a4a2a 100644 --- a/site/docs/release/SOCIAL_LAUNCH_EN.md +++ b/site/docs/release/SOCIAL_LAUNCH_EN.md @@ -15,11 +15,11 @@ Humanities Superpowers is not a tool that writes papers for researchers. It is a The repository includes: - 13 core research skills, from formulating a question to pre-submission verification -- a research orchestrator that diagnoses the current state and selects the smallest valid workflow +- 1 Level 3 router that diagnoses the current state and selects the smallest valid workflow - quality gates using `PASS`, `CONDITIONAL PASS`, and `FAIL` - concept-lineage mapping, close reading, argument stress testing, citation auditing, terminology control, manuscript review, and peer-review response - rollback to an earlier research stage when a downstream failure reveals an upstream problem -- installation guidance for Claude Code, Codex, and Cursor +- tested installation routes for Claude Code and OpenAI Codex, plus not-yet-verified Cursor guidance - an English white paper, bilingual documentation, worked examples, schemas, and automated validation The project is guided by one sentence: @@ -69,7 +69,7 @@ Rather than automating paper writing, the project supports research judgment acr Unverified citations and unsupported claims are preserved as failures rather than polished into apparently complete scholarship. When a failure originates upstream, the research orchestrator routes the project back to the earliest relevant stage. -The repository supports Claude Code, Codex, and Cursor and is released under the MIT License. +The repository has been tested with Claude Code and OpenAI Codex. It also provides Cursor installation guidance that has not yet been independently verified. The project is released under the MIT License. Repository: [REPOSITORY_URL] Documentation: [PAGES_URL] @@ -91,7 +91,7 @@ AI can generate a polished paragraph long before a research question, source bas - Did the manuscript actually change before the reviewer response says it did? - Is the submission package genuinely ready? -The repository includes 13 research skills, an orchestrator, explicit quality gates, and worked examples. +The repository includes 13 core research skills, 1 Level 3 router, explicit quality gates, and worked examples. [REPOSITORY_URL] @@ -105,11 +105,11 @@ Coding agents increasingly rely on structured planning, tests, debugging, and ve Included: -- 13 Level-2 research skills -- a Level-3 research orchestrator +- 13 core research skills at Level 2 +- 1 Level 3 router - research-object, gate-report, and session schemas - deterministic conformance and integration tests -- Claude Code, Codex, and Cursor installation paths +- tested Claude Code and OpenAI Codex routes, plus unverified Cursor guidance [REPOSITORY_URL] @@ -125,7 +125,7 @@ I therefore wanted to build something different from a better paper-writing prom The result is **Humanities Superpowers**. -It includes 13 research skills and an orchestrator covering the path from research-question formulation to citation auditing, manuscript review, peer-review revision, and submission verification. I hope it can grow as a public methodology that researchers use, criticize, and improve together. +It includes 13 core research skills and 1 Level 3 router covering the path from research-question formulation to citation auditing, manuscript review, peer-review revision, and submission verification. I hope it can grow as a public methodology that researchers use, criticize, and improve together. [REPOSITORY_URL] diff --git a/site/docs/release/SOCIAL_LAUNCH_KO.md b/site/docs/release/SOCIAL_LAUNCH_KO.md index 68ab565..5c811fe 100644 --- a/site/docs/release/SOCIAL_LAUNCH_KO.md +++ b/site/docs/release/SOCIAL_LAUNCH_KO.md @@ -14,12 +14,12 @@ Humanities Superpowers는 AI가 논문을 대신 써주는 도구가 아닙니 프로젝트에는 다음이 포함되어 있습니다. -- 연구 질문 형성부터 제출 전 검증까지 이어지는 13개 핵심 스킬 -- 현재 연구 상태를 진단하고 필요한 스킬을 연결하는 연구 오케스트레이터 +- 연구 질문 형성부터 제출 전 검증까지 이어지는 13개 핵심 연구 스킬 +- 현재 연구 상태를 진단하고 필요한 스킬을 연결하는 1개 Level 3 라우터 - `PASS`, `CONDITIONAL PASS`, `FAIL`로 작동하는 연구 품질 게이트 - 인용 감사, 개념 계보, 정밀 읽기, 논증 스트레스 테스트, 심사의견 대응 - 실패 원인이 발견되면 이전 단계로 돌아가는 rollback 방식 -- Claude Code, Codex, Cursor용 설치 안내 +- Claude Code와 OpenAI Codex의 검증된 설치 경로 및 아직 독립 검증되지 않은 Cursor 안내 - 영문 백서, 한·영문 문서, 실제 예제와 자동 검증 스크립트 이 프로젝트의 핵심 원칙은 단순합니다. @@ -70,7 +70,7 @@ AI가 논문을 대신 쓰게 하는 도구가 아니라, 연구 질문·개념 이 프로젝트는 논문 자동 작성 도구가 아니라 연구 질문 형성, 범위 설정, 개념 계보, 선행연구 대화, 정밀 읽기, 논증 설계, 반론 검토, 인용 감사, 용어 일관성, 심사의견 대응, 제출 전 검증을 연결하는 연구 품질 프레임워크입니다. -검증되지 않은 인용이나 과도한 주장은 `FAIL`로 남기며, 문제가 발견되면 원인이 발생한 이전 단계로 되돌아가도록 설계했습니다. Claude Code, Codex, Cursor에서 사용할 수 있고 MIT License로 공개합니다. +검증되지 않은 인용이나 과도한 주장은 `FAIL`로 남기며, 문제가 발견되면 원인이 발생한 이전 단계로 되돌아가도록 설계했습니다. Claude Code와 OpenAI Codex에서 설치·검증했고, Cursor에는 아직 독립 검증되지 않은 설치 안내를 제공합니다. MIT License로 공개합니다. 저장소: [REPOSITORY_URL] 문서: [PAGES_URL] @@ -92,7 +92,7 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 - 심사의견에 답변서만 쓰고 원고 수정은 빠뜨리지 않았는가? - 지금 원고는 정말 제출 가능한가? -13개 연구 스킬과 제출 전 품질 게이트를 무료로 공개했습니다. +13개 핵심 연구 스킬과 1개 Level 3 라우터, 제출 전 품질 게이트를 무료로 공개했습니다. [REPOSITORY_URL] @@ -104,13 +104,13 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 **Humanities Superpowers**는 composable agent skills의 발상을 인문학 연구 방법론으로 옮긴 오픈소스 프로젝트입니다. -- 13 Level-2 research skills -- Level-3 research orchestrator +- 13 core research skills at Level 2 +- 1 Level 3 router - research state machine - quality gates and rollback - research-object and session JSON schemas - deterministic conformance tests -- Claude Code, Codex, Cursor support +- tested Claude Code and OpenAI Codex routes, plus unverified Cursor guidance [REPOSITORY_URL] @@ -126,7 +126,7 @@ AI에게 “논문을 써 달라”고 요청하면 문장은 빨리 생기지 그 결과가 Humanities Superpowers입니다. -이 프로젝트는 연구 질문부터 인용 감사, 논증 검토, 심사의견 대응, 제출 전 검증까지 13개 스킬과 연구 오케스트레이터로 구성되어 있습니다. 아직 부족하겠지만, 연구자들이 함께 사용하고 비판하며 발전시키는 공개 방법론이 되기를 바랍니다. +이 프로젝트는 연구 질문부터 인용 감사, 논증 검토, 심사의견 대응, 제출 전 검증까지 13개 핵심 연구 스킬과 1개 Level 3 라우터로 구성되어 있습니다. 아직 부족하겠지만, 연구자들이 함께 사용하고 비판하며 발전시키는 공개 방법론이 되기를 바랍니다. [REPOSITORY_URL] diff --git a/site/docs/skills.md b/site/docs/skills.md index 480d8e0..9a154f8 100644 --- a/site/docs/skills.md +++ b/site/docs/skills.md @@ -1,5 +1,7 @@ # Skills +The repository contains 14 `SKILL.md` files: 13 core research skills and the separate `using-humanities-superpowers` Level 3 router. + ## Orchestration - `using-humanities-superpowers` — diagnoses research state, selects the smallest valid workflow, preserves gates, and manages rollback. @@ -29,4 +31,4 @@ - `responding-to-peer-review` - `verifying-before-submission` -Each core skill has an explicit contract describing what it accepts, requires, produces, guarantees, does not guarantee, and when it must fail. +Each file has an explicit contract describing what it accepts, requires, produces, guarantees, does not guarantee, and when it must fail.