Metadata-Version: 2.4
Name: norn-cli
Version: 0.7.3
Summary: Norn: a provider-neutral multi-agent development harness
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/uruca-kk/norn
Project-URL: Issues, https://github.com/uruca-kk/norn/issues
Project-URL: Changelog, https://github.com/uruca-kk/norn/blob/main/CHANGELOG.md
Keywords: agents,cli,codex,claude,testing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.10
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Dynamic: license-file

# Norn

Provider-neutral multi-agent development harness for local subscription CLIs. The name evokes
the Norns who shape fate: the harness coordinates independent agents toward a bounded outcome.

> Status: beta. The `norn-cli` distribution is published to PyPI; the source
> repository remains private during the beta period.

Norn provides configuration, CLI, run-state, event journal, recovery,
human-readable escalation reports, provider-neutral adapters, and an executable
multi-role delivery pipeline for Codex, Claude Code, Grok Build, and future
command-based subscription CLIs.

```bash
norn init
norn --version
norn doctor
norn validate-config
norn providers
norn plan "add an audit log"
norn run "add an audit log"
```

Install the bundled explicit-invocation skill for both Codex and Claude Code:

```bash
norn install-skill --target all --scope project --project /path/to/repository
```

This writes `.agents/skills/norn` for Codex and `.claude/skills/norn` for Claude Code. Use
`$norn` in Codex or `/norn` in Claude Code. Install a single user-level copy with
`--target codex|claude --scope user`; use `--force` only to replace an existing
copy intentionally. Loading the skill never starts a model-consuming lifecycle
unless the user explicitly requests `plan` or `run`.

See [Installation](docs/installation.md) for isolated `uv tool`, `pipx`, and
virtual-environment installs from PyPI.

`plan` runs orchestration, planning, and plan review. `run` continues through
implementation, language-aware local tests/lint, the four tester roles, triage,
and final gate. UI changes require an independent E2E result from every tester.
Each required E2E result must include the executed argv, exit code, a concise
result summary, and at least one non-empty artifact created in that tester's
assigned evidence directory. The harness rejects missing, stale, symlinked, or
out-of-directory evidence and archives accepted files under
`.norf/runs/<run-id>/artifacts/e2e/`.

To implement a previously approved plan without invoking orchestration, planning,
or plan review again, pass the successful `plan` run ID with the identical request:

```bash
norn plan "add an audit log"
norn run "add an audit log" --from-plan <plan-run-id>
```

Norn verifies the source run mode and status, project root, request text, and saved
artifact schemas before creating the implementation worktree.

For Codex tester roles, the adapter keeps `workspace-write` filesystem isolation
and enables command networking through a loopback-only proxy allowlist
(`localhost` and `127.0.0.1`). Planning and implementation roles retain their
normal network-off policy.

Profiles keep a stable logical model name while optionally mapping it to a
provider-specific identifier. For example, Codex Sol is configured as:

```yaml
candidates:
  - provider: codex-cli
    model: sol
    model_id: gpt-5.6-sol
    effort: high
```

Round limits are configured under `limits` or overridden per invocation:

```bash
norn run "task" --max-rounds 5 --max-total-rounds 12 \
  --max-planner-retries 2 --max-final-replans 2
```

Known Python, Node, Rust, and Go gates are auto-detected. Projects can define
additional commands as shell-free argv lists:

```yaml
gates:
  enabled: true
  auto_detect: true
  commands:
    - name: integration
      kind: test
      command: [python3, -m, pytest, tests/integration]
```

Each run records role responses, model selections, attempts, findings, test
results, and round history below `.norf/runs/<run-id>/`. Any non-successful stop
also produces `escalation-report.md` and `escalation.json` for human judgment.

By default, `run` requires a clean Git repository and implements inside a
detached `.norf/worktrees/<run-id>/` worktree. Set `git.worktree: false` only when
direct changes to the selected project directory are intentional.

## Development and packaging

Install the local development tools and run the same checks as CI:

```bash
python3 -m pip install --editable ".[dev]"
ruff format --check .
ruff check .
python3 -m unittest discover -v
python3 -m build
python3 scripts/package_smoke.py dist/norn_cli-0.7.3-py3-none-any.whl
```

CI runs the quality suite on Python 3.12, 3.13, and 3.14, then installs the
built wheel in a clean virtual environment and verifies both Codex and Claude
skill copies. It uploads the distributions as a short-lived workflow artifact.
Publishing a GitHub Release runs the same deterministic gates before sending
the verified artifact to PyPI through OIDC Trusted Publishing; neither workflow
invokes subscription models.

Release acceptance is intentionally split in two: CI performs deterministic
package checks, while local acceptance invokes the authenticated subscription
CLIs. Follow [Release acceptance](docs/acceptance.md) before promoting a release.
See [CHANGELOG](CHANGELOG.md) for version history and [Security](SECURITY.md) for
private vulnerability reporting.

The canonical command is `norn`. The legacy `norf-harness` executable remains an alias during
the pre-1.0 migration; new automation should use `norn`.

## License

Copyright 2026 uruca-kk. Licensed under the
[Apache License 2.0](LICENSE).
