Skip to content
Back to search

J-Space-Cognition-Suite

J-Space Cognition Suite — a model-agnostic inference-time control suite for deep reasoning, long-horizon work, verification, and recovery. Based on Anthropic's J-space global workspace research.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tiger3807861189--j-space-cognition-suite/badge.svg)](/listings/tiger3807861189--j-space-cognition-suite)

HTML

<a href="/listings/tiger3807861189--j-space-cognition-suite"><img src="/api/listings/tiger3807861189--j-space-cognition-suite/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need a host that can load a local `SKILL.md` and retrieve its supporting files. Python 3.10+ is needed for executable controllers and validation; low/medium can use the documented prose fallback. No pip dependencies or background service are required.

1. Copy the complete [`j-space/`](j-space/) directory into your host's Skills directory. Obtain that directory from the host's own configuration; no universal location or invocation syntax applies to every host. Keep `SKILL.md`, `modules/`, `references/`, and `scripts/` together; avoid an extra nested `j-space/j-space/` directory. Copy `LICENSE` and `THIRD_PARTY_NOTICES.md` alongside the installed `SKILL.md` when distributing the standalone skill. Use an empty destination to avoid mixing installs. 2. Use Python 3.10 or later to verify the installed directory:

   <python-command> <skill-root>/scripts/verify_suite.py

3. Reload the host if it discovers skills only at startup. Select `j-space` through its skill UI. Use `$j-space` or `/j-space` only if that host documents the syntax; otherwise ask it to read the installed `SKILL.md` explicitly. Confirm it can retrieve one routed module and execute the installed controller's `--help` if you need strict gates. 4. Give it the task and its acceptance conditions:

   Use j-space to modify this repository. Inspect the existing contracts, maintain a
   source-backed map, delegate independent work where useful, and verify the final behavior.

Replace `<python-command>` with your available `python`, `python3`, or `py -3` command. Resolve `<skill-root>` to the installed directory. Keep the task directory as the working directory, or pass `--root TASK_DIRECTORY` before a controller subcommand.

For a path with spaces in Bash:

python3 "/path with spaces/j-space/scripts/control.py" --root "/task directory" status

For a quoted interpreter path in PowerShell:

& "C:\Python313\python.exe" "C:\Skills\j-space\scripts\control.py" --root "D:\Task Directory" status

Run `status` after initializing the task. UTF-8 input supports English and Chinese task content; use the language requested by the user for deliverables. Run controllers in the target project's task directory, not the installed skill directory. Installing the files does not automatically register hooks, launch agents, or grant tool access.

> **Intended use.** This suite is designed for real engineering and production-oriented > projects with contracts, dependencies, verification, and recovery needs. It is not aimed > at toy demonstrations such as “a pelican riding a bicycle.” Its suitability for serious > work is a design focus, not a guarantee that any untested deployment is production-ready.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 340 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # J-Space Cognition Suite SV1
  2. [Simplified Chinese](README.zh-CN.md)
  3. [![Concept DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21971181.svg)](https://doi.org/10.5281/zenodo.21971181)
  4. J-Space is an inference-time workspace and control suite for complex reasoning, repository
  5. engineering, coordinated agents, and authorized security analysis. You install one skill,
  6. load relevant modules, and keep long-task decisions connected to durable evidence.
  7. Its thirteen modules share one premise and one routing entry. Standard-library Python
  8. scripts persist state, reread actual source text, detect stale maps and evidence, and return
  9. blocking results when a required condition is missing. The host supplies tools and agents.
  10. ## Quick start
  11. You need a host that can load a local `SKILL.md` and retrieve its supporting files.
  12. Python 3.10+ is needed for executable controllers and validation; low/medium can use the
  13. documented prose fallback. No pip dependencies or background service are required.
  14. 1. Copy the complete [`j-space/`](j-space/) directory into your host's Skills directory.
  15. Obtain that directory from the host's own configuration; no universal location or
  16. invocation syntax applies to every host. Keep `SKILL.md`, `modules/`, `references/`,
  17. and `scripts/` together; avoid an extra nested `j-space/j-space/` directory.
  18. Copy `LICENSE` and `THIRD_PARTY_NOTICES.md` alongside the installed `SKILL.md` when
  19. distributing the standalone skill. Use an empty destination to avoid mixing installs.
  20. 2. Use Python 3.10 or later to verify the installed directory:
  21. ```text
  22. <python-command> <skill-root>/scripts/verify_suite.py
  23. ```
  24. 3. Reload the host if it discovers skills only at startup. Select `j-space` through its
  25. skill UI. Use `$j-space` or `/j-space` only if that host documents the syntax; otherwise
  26. ask it to read the installed `SKILL.md` explicitly. Confirm it can retrieve one routed
  27. module and execute the installed controller's `--help` if you need strict gates.
  28. 4. Give it the task and its acceptance conditions:
  29. ```text
  30. Use j-space to modify this repository. Inspect the existing contracts, maintain a
  31. source-backed map, delegate independent work where useful, and verify the final behavior.
  32. ```
  33. Replace `<python-command>` with your available `python`, `python3`, or `py -3` command.
  34. Resolve `<skill-root>` to the installed directory. Keep the task directory as the working
  35. directory, or pass `--root TASK_DIRECTORY` before a controller subcommand.
  36. For a path with spaces in Bash:
  37. ```bash
  38. python3 "/path with spaces/j-space/scripts/control.py" --root "/task directory" status
  39. ```
  40. For a quoted interpreter path in PowerShell:
  41. ```powershell
  42. & "C:\Python313\python.exe" "C:\Skills\j-space\scripts\control.py" --root "D:\Task Directory" status
  43. ```
  44. Run `status` after initializing the task. UTF-8 input supports English and Chinese task
  45. content; use the language requested by the user for deliverables.
  46. Run controllers in the target project's task directory, not the installed skill directory.
  47. Installing the files does not automatically register hooks, launch agents, or grant tool access.
  48. > **Intended use.** This suite is designed for real engineering and production-oriented
  49. > projects with contracts, dependencies, verification, and recovery needs. It is not aimed
  50. > at toy demonstrations such as “a pelican riding a bicycle.” Its suitability for serious
  51. > work is a design focus, not a guarantee that any untested deployment is production-ready.
  52. ## Operating levels
  53. | Level | Use | Control |
  54. |---|---|---|
  55. | `low` | A direct answer checkable at a glance | Fast pass; no persistent setup |
  56. | `medium` | A bounded deliverable with a few dependent steps | Full pass; selective modules and delivery audit |
  57. | `high` | Multi-file, multi-stage, or persistent work | Loop; shared state, source refresh, evidence checks |
  58. | `xhigh` | Difficult integration or competing approaches that benefit from a team | Loop plus bounded agents, second consideration, and independent review |
  59. `media` is an accepted alias for `medium`. Raise the level when the task's uncertainty or
  60. dependencies require it. Use agents proactively when independent work justifies coordination.
  61. When the host lacks agents, record the limitation and perform sequential checks.
  62. ## A short tutorial for all four levels
  63. Select the skill first. In commands below, replace `<python-command>` and `<skill-root>`
  64. with your installed interpreter and skill directory, quote paths containing spaces, and
  65. work in the target task directory. The example artifact names refer to files you create
  66. from actual work and checks; do not create empty or fabricated evidence just to pass a gate.
  67. ### low — a bounded check inside engineering work
  68. Ask: “Use j-space at low to check whether this configuration change preserves the timeout
  69. unit. State the conclusion and its evidence; do not expand the task.” Read the relevant
  70. input, check the one constraint, and return the result. No state initialization is required.
  71. Escalate if the check exposes cross-file dependencies or unresolved uncertainty.
  72. ### medium — a small deliverable with dependent steps
  73. Ask: “Use j-space at medium to update this API example and verify its parameters against
  74. the implementation. Keep a short record of the goal, uncertainty, and observed checks.”
  75. Optionally use the lightweight ledger:
  76. ```text
  77. <python-command> <skill-root>/scripts/jspace.py note --goal "API example matches implementation" --next "Inspect the endpoint"
  78. <python-command> <skill-root>/scripts/jspace.py note --open "Does the example cover required inputs?" --settled-by "Inspect the endpoint and run the example"
  79. <python-command> <skill-root>/scripts/jspace.py seam
  80. ```
  81. Inspect and run the example, then record the actual outcome with
  82. `note --check "Observed result" --by "manual inspection of each input and execution of the reported case" --close 1`.
  83. Write `answer.md`, then run `jspace.py ship answer.md`. This audits text heuristically;
  84. findings are advisory, while unreadable/oversized input is rejected. It does not prove the
  85. API behavior. Do not maintain this ledger alongside the strict controller for the same task.
  86. ### high — repository work from inspection to delivery
  87. Ask: “Use j-space at high to repair this repository issue. Preserve public contracts, keep
  88. a source-backed map, run the relevant tests, and finish with evidence against each requirement.”
  89. Follow the **Shared control** section to initialize, read sources, create/sync/view the map,
  90. and pass the work gate. Perform the work; record real verification in `evidence/root.txt`
  91. and a separate acceptance checklist in `evidence/completion.txt`. Keep `src/router.py` below
  92. only if it is a material source dependency; substitute your actual sources and repeat `--source` as needed.
  93. ```text
  94. <python-command> <skill-root>/scripts/control.py pulse --event checkpoint
  95. <python-command> <skill-root>/scripts/control.py report --agent root --round 1 --summary "Observed repair and coverage" --evidence evidence/root.txt --completion evidence/completion.txt --source src/router.py --next "Deliver checked result"
  96. <python-command> <skill-root>/scripts/control.py repo sync --map repo-map.json
  97. <python-command> <skill-root>/scripts/control.py repo view --agent root
  98. <python-command> <skill-root>/scripts/control.py repo check
  99. <python-command> <skill-root>/scripts/control.py check --stage ship
  100. ```
  101. Update the map's meaning before that final sync. Creating report/checklist files changes
  102. the inventory too. Resolve open questions and security candidates before shipment. Exit 0
  103. allows delivery; a nonzero result names an unmet condition. Repair that condition before
  104. checking again; identical retries without changed evidence are not recovery.
  105. ### xhigh — actual independent work and integration
  106. Ask: “Use j-space at xhigh for this integration. Assign an independent contract review to
  107. a real child agent, request its second consideration, reproduce material findings, and
  108. retain disagreements until a discriminating check resolves them.” From an initialized high
  109. task, route before creating reports for the current scope:
  110. ```text
  111. <python-command> <skill-root>/scripts/control.py route --level xhigh --module modules/repository.md --reason "Independent integration review"
  112. <python-command> <skill-root>/scripts/control.py read --agent root
  113. <python-command> <skill-root>/scripts/control.py agent add --id reviewer --parent root --task "Inspect the integration contract" --owns src
  114. <python-command> <skill-root>/scripts/control.py pulse --event resume --agent reviewer
  115. <python-command> <skill-root>/scripts/control.py repo view --agent reviewer
  116. <python-command> <skill-root>/scripts/control.py check --stage work --agent reviewer
  117. ```
  118. The host must actually launch that child and deliver its own pulse output; an ID is not an
  119. independent model. The child writes distinct `evidence/review-1.txt` and `evidence/review-2.txt`
  120. after two substantive passes, then submits each through `report --agent reviewer --round 1`
  121. and `--round 2`, supplying `--summary`, `--evidence`, `--source`, and `--next` each time.
  122. Root independently checks the finding and writes a separate `evidence/acceptance.txt`:
  123. ```text
  124. <python-command> <skill-root>/scripts/control.py review --agent root --target reviewer --verdict accepted --evidence evidence/acceptance.txt
  125. ```
  126. Root writes and submits its own report and completion checklist as in high. After all
  127. artifacts are stable, update/sync the map, have **every active agent** run its own `read`
  128. and `repo view`, then run the root ship gate. Goal/core/route changes require fresh report
  129. cycles and reviews. A lost child uses `agent retire` with a reason and active successor,
  130. followed by fresh root completion. If the host truly lacks delegation, record
  131. `note --solo-reason "Specific unavailable capability and resulting review limit"`; do not
  132. simulate independence by driving two identities yourself.
  133. ## Shared control
  134. Initialize a repository task with its relevant module:
  135. ```text
  136. <python-command> <skill-root>/scripts/control.py init --goal "Acceptance criteria" --next "Inspect entry points" --level high --module modules/repository.md
  137. <python-command> <skill-root>/scripts/control.py read --agent root
  138. ```
  139. Maintain a semantic map as a task file, for example `repo-map.json`:
  140. ```json
  141. {
  142. "summary": "Service boundaries and validation routes",
  143. "areas": [{"path": "src", "purpose": "Request handling and business rules"}],
  144. "facts": [{"claim": "Requests enter through the router", "evidence": "src/router.py"}],
  145. "dependencies": [{"from": "src/router.py", "to": "src/service.py", "contract": "Validated request"}],
  146. "tests": [{"path": "tests", "covers": "Request validation and service behavior"}],
  147. "unknowns": [{"question": "How do retries affect writes?", "settled_by": "Inspect transaction boundaries and test repeated requests"}]
  148. }
  149. ```
  150. Replace example paths and claims with inspected files in your actual task. Then:
  151. ```text
  152. <python-command> <skill-root>/scripts/control.py repo sync --map repo-map.json
  153. <python-command> <skill-root>/scripts/control.py repo view --agent root
  154. <python-command> <skill-root>/scripts/control.py check --stage work --agent root
  155. <python-command> <skill-root>/scripts/control.py pulse --event tool --agent root
  156. <python-command> <skill-root>/scripts/control.py note --next "Validate the changed behavior"
  157. ```
  158. Read the map before edits. Update its semantic claims after source changes and verification,
  159. then sync and view it again. A fingerprint checks freshness; source inspection and tests
  160. establish whether the claims are true. The controller writes `.jspace/control.json` under a
  161. process lock and derives the shared `.jspace/CONTROL.md` view from that canonical state.
  162. | Capability | Runtime behavior |
  163. |---|---|
  164. | Source refresh | Reads current entry/module files, emits their actual text, and records per-agent hashes and times |
  165. | Pulse schedule | Refreshes on recovery and phase events, configured call count, or elapsed interval |
  166. | Repository memory | Stores a semantic map and content inventory, detects changes, and records map views |
  167. | Durable collaboration | Records bounded ownership, rounds of reports, evidence fingerprints, and independent reviews |
  168. | Security evidence | Tracks candidate, confirmed, rejected, and fixed dispositions with reproduction and controls |
  169. | Work/delivery gates | Returns nonzero when required state, source receipts, map, or evidence is missing or stale |
  170. Read [the controller reference](j-space/references/controller.md) for complete commands,
  171. schemas, evidence rules, budget semantics, and recovery. The optional
  172. [`jspace.py`](j-space/scripts/jspace.py) provides a small standalone ledger and heuristic
  173. text audit for bounded work. Its `ship` output is advisory; use `control.py` for strict gates.
  174. Use `route --level xhigh --module modules/repository.md --reason "Integration needs independent review"`
  175. to raise the level or change active optional modules while preserving task state. Record
  176. checkpoints with `note --check "Claim" --by "Method and coverage" --evidence PATH`.
  177. Before shipment, root submits `report` with `--completion PATH` containing the goal-by-goal
  178. acceptance check; each delegate supplies its reports and independent review. Then run
  179. `check --stage ship`. The controller reference contains the complete argument sequence.
  180. ## Host integration and refresh
  181. To make invocation automatic, wire your host's events to
  182. [`host_bridge.py`](j-space/scripts/host_bridge.py), feed its returned context to the agent,
  183. and honor its `allow` decision. [Host integration](j-space/references/host-integration.md)
  184. defines the JSON contract, event mapping, a minimal adapter, and a connection test.
  185. Default source refresh is five tool events or ten minutes, whichever is encountered first,
  186. with immediate refresh at relevant phase and recovery events. These are configurable
  187. engineering defaults; measure drift and input cost for your host. Time-based refresh runs
  188. when an event arrives, and the scripts do not inject into an idle model on their own.
  189. With no native hooks, call the same commands at explicit boundaries and describe the setup
  190. as cooperative control. With no Python or filesystem, keep a restated conversation ledger
  191. and retrieve source text with available tools. Report the missing executable safeguards.
  192. ## Agents, repositories, and security
  193. - [Orchestration](j-space/modules/orchestration.md): give every child the complete skill,
  194. register its ownership and parent, and require its own source reads. Preserve reports in
  195. the shared record, return to the same child for a focused second pass, and independently
  196. check the resulting evidence. Resolve competing proposals through tests, retaining dissent.
  197. - [Repository](j-space/modules/repository.md): map contracts, entry points, dependencies,
  198. test routes, and unknown areas. Read before editing and synchronize after verification.
  199. Use separate candidate checkouts when multiple approaches need conflicting writes.
  200. - [Cyber](j-space/modules/cyber.md): trace controlled input to a violated property within
  201. the authorized environment. Preserve reproduction, expected/observed behavior, a negative
  202. control, and a supported disposition. Verify repairs at the underlying invariant.
  203. - [Epistemics](j-space/modules/epistemics.md): distinguish observation, inference, and
  204. uncertainty; recover tacit constraints and turn newly exposed gaps into specific probes.
  205. The existing workspace operations—introspection, directed focus, reasoning bridges, broadcast,
  206. capacity, monitoring, shorthand, markers, and empirics—route into these engineering modules.
  207. Keep one or two ideas active and persist the rest. A child gets the complete suite while
  208. loading only what its current phase requires.
  209. ## Validation and evaluation
  210. Run from the repository root:
  211. ```text
  212. <python-command> j-space/scripts/verify_suite.py
  213. <python-command> -m unittest discover -s tests -v
  214. ```
  215. CI configures Windows, Linux, and macOS. The integrity check covers the entry, shared
  216. premise, module structure, routes, local links, and Python syntax. Regression tests exercise
  217. state, input validation, Unicode, persistence, freshness, coordination, and host events.
  218. Repository gates revalidate explicitly cited map facts even in inventory-excluded directories.
  219. Every active participant must view the final map; goal/core/route changes require fresh
  220. reports and reviews. Use `agent retire` to preserve an abandoned registration's history and
  221. handoff while root reassesses completion. For large trees, configure the trusted bridge's
  222. `--timeout-seconds` and outer host deadline based on measured gate latency. Full content
  223. hashing remains in force. See [the controller contract](j-space/references/controller.md).
  224. Tests establish the implemented behaviors they cover; they do not establish universal model
  225. performance gains or guarantee a host honors the protocol. Check CI results for the exact
  226. commit and environment you plan to use.
  227. ## Project layout
  228. ```text
  229. J-Space Cognition Suite SV1/
  230. ├── .github/workflows/verify.yml
  231. ├── .gitignore
  232. ├── CITATION.cff
  233. ├── CONTRIBUTING.md
  234. ├── LICENSE
  235. ├── README.md
  236. ├── README.zh-CN.md
  237. ├── THIRD_PARTY_NOTICES.md
  238. ├── tests/
  239. └── j-space/
  240. ├── SKILL.md
  241. ├── modules/ # Thirteen selectively loaded protocols
  242. ├── references/ # Science, evidence, examples, and runtime contracts
  243. └── scripts/
  244. ├── control.py # Persistent gates, maps, agents, and evidence
  245. ├── host_bridge.py # Portable event/context adapter
  246. ├── jspace.py # Standalone lightweight ledger and text audit
  247. ├── workspace-ledger.md # Lightweight ledger contract
  248. └── verify_suite.py # Authoring integrity checks
  249. ```
  250. ## Research and claim boundaries
  251. [Engineering evidence](j-space/references/engineering-evidence.md) links the primary sources
  252. for J-space, the four knowledge quadrants, LLM-as-a-Verifier, team reconciliation, repository
  253. wikis, and re-reading. [The science reference](j-space/references/j-space-science.md) preserves
  254. the suite's research terminology and source excerpts.
  255. The suite acts through instructions, tools, external state, and host event handling. It
  256. does not modify model weights, measure neural workspace size, or guarantee activation of
  257. different MoE experts. Use sparse routing, broad review, and retained contrary evidence as
  258. engineering patterns; establish their value through observable results.
  259. SV1 is an architectural upgrade. SV1's data and conclusions stand on their own stated
  260. measurement basis; nothing is carried forward from an earlier version.
  261. ## Contributors and license
  262. Community contributors include [@forever-ivy](https://github.com/forever-ivy),
  263. [@lanting200](https://github.com/lanting200), [@afeer123](https://github.com/afeer123),
  264. [@ShaneLau2](https://github.com/ShaneLau2), [@menoxz](https://github.com/menoxz), and
  265. [@raelldottin](https://github.com/raelldottin).
  266. J-Space uses [Apache License 2.0](LICENSE). Preserve attribution and the
  267. [third-party notices](THIRD_PARTY_NOTICES.md); external materials retain their own terms.
  268. When redistributing only `j-space/`, include copies of both files. The concept DOI covers
  269. the project; Zenodo mints the SV1 version DOI when the release is archived.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.